@cxyhhhhh/openclaw-qqbot 1.6.7-alpha.1

package/src/message-gating.ts

@@ -0,0 +1,190 @@
+/**
+ * 群消息门控 — 统一入口。
+ *
+ * 将 ignoreOtherMentions / shouldBlock / mentionGating 三层判断收敛到
+ * 一个纯函数 resolveGroupMessageGate() 中，让 gateway 主流程只关心一个结果。
+ *
+ * 按优先级串行检查：
+ *   1. ignoreOtherMentions — @了其他人但未 @bot → 丢弃（记历史）
+ *   2. shouldBlock         — 未授权控制命令静默拦截
+ *   3. mentionGating       — requireMention 门控 + 命令旁路
+ */
+
+// ────────────────────── Types ──────────────────────
+
+export type MentionGateResult = {
+  effectiveWasMentioned: boolean;
+  shouldSkip: boolean;
+};
+
+export type MentionGateWithBypassResult = MentionGateResult & {
+  shouldBypassMention: boolean;
+};
+
+export type GroupMessageGateAction =
+  /** @了其他人但未 @bot，丢弃并记录历史 */
+  | "drop_other_mention"
+  /** 未授权控制命令，静默拦截 */
+  | "block_unauthorized_command"
+  /** 非 @bot 消息，记录历史后跳过 AI */
+  | "skip_no_mention"
+  /** 正常放行，交给 AI */
+  | "pass";
+
+export type GroupMessageGateResult = {
+  action: GroupMessageGateAction;
+  /** 仅 action=pass|skip_no_mention 时有值 */
+  effectiveWasMentioned: boolean;
+  shouldBypassMention: boolean;
+};
+
+export type GroupMessageGateParams = {
+  // ── ignoreOtherMentions 层 ──
+  ignoreOtherMentions: boolean;
+  hasAnyMention: boolean;
+  wasMentioned: boolean;
+  implicitMention: boolean;
+
+  // ── shouldBlock 层 ──
+  allowTextCommands: boolean;
+  isControlCommand: boolean;
+  commandAuthorized: boolean;
+
+  // ── mentionGating 层 ──
+  requireMention: boolean;
+  canDetectMention: boolean;
+};
+
+// ────────────────────── Core Logic ──────────────────────
+
+/**
+ * 基础 mention 门控纯函数。
+ * effectiveWasMentioned = wasMentioned || implicitMention || shouldBypassMention
+ * shouldSkip = requireMention && canDetectMention && !effectiveWasMentioned
+ */
+function resolveMentionGating(params: {
+  requireMention: boolean;
+  canDetectMention: boolean;
+  wasMentioned: boolean;
+  implicitMention?: boolean;
+  shouldBypassMention?: boolean;
+}): MentionGateResult {
+  const implicit = params.implicitMention === true;
+  const bypass = params.shouldBypassMention === true;
+  const effectiveWasMentioned = params.wasMentioned || implicit || bypass;
+  const shouldSkip = params.requireMention && params.canDetectMention && !effectiveWasMentioned;
+  return { effectiveWasMentioned, shouldSkip };
+}
+
+/**
+ * 带命令旁路的 mention 门控。
+ *
+ * shouldBypassMention 条件（全部满足时才旁路）：
+ * 1. requireMention    — 开启了 mention 要求
+ * 2. !wasMentioned     — 没有被直接 mention
+ * 3. !hasAnyMention    — 消息中没有任何 @（防止 @ 其他人的消息误 bypass）
+ * 4. allowTextCommands — 文本命令已启用
+ * 5. commandAuthorized — 发送者有命令权限
+ * 6. hasControlCommand — 消息是合法控制命令
+ */
+function resolveMentionGatingWithBypass(params: {
+  requireMention: boolean;
+  canDetectMention: boolean;
+  wasMentioned: boolean;
+  implicitMention?: boolean;
+  hasAnyMention?: boolean;
+  allowTextCommands: boolean;
+  hasControlCommand: boolean;
+  commandAuthorized: boolean;
+}): MentionGateWithBypassResult {
+  const shouldBypassMention =
+    params.requireMention &&
+    !params.wasMentioned &&
+    !(params.hasAnyMention ?? false) &&
+    params.allowTextCommands &&
+    params.commandAuthorized &&
+    params.hasControlCommand;
+  return {
+    ...resolveMentionGating({
+      requireMention: params.requireMention,
+      canDetectMention: params.canDetectMention,
+      wasMentioned: params.wasMentioned,
+      implicitMention: params.implicitMention,
+      shouldBypassMention,
+    }),
+    shouldBypassMention,
+  };
+}
+
+// ────────────────────── Unified Gate ──────────────────────
+
+/**
+ * 群消息统一门控，按优先级串行判定：
+ *
+ *   1. ignoreOtherMentions — @了其他人但未 @bot → drop_other_mention
+ *   2. shouldBlock         — 未授权控制命令      → block_unauthorized_command
+ *   3. mentionGating       — 未满足 @bot 条件    → skip_no_mention
+ *   4. 通过所有检查                              → pass
+ */
+export function resolveGroupMessageGate(params: GroupMessageGateParams): GroupMessageGateResult {
+  const {
+    ignoreOtherMentions,
+    hasAnyMention,
+    wasMentioned,
+    implicitMention,
+    allowTextCommands,
+    isControlCommand,
+    commandAuthorized,
+    requireMention,
+    canDetectMention,
+  } = params;
+
+  // ── Layer 1: ignoreOtherMentions ──
+  if (
+    ignoreOtherMentions &&
+    hasAnyMention &&
+    !wasMentioned &&
+    !implicitMention
+  ) {
+    return {
+      action: "drop_other_mention",
+      effectiveWasMentioned: false,
+      shouldBypassMention: false,
+    };
+  }
+
+  // ── Layer 2: shouldBlock 未授权控制命令 ──
+  if (allowTextCommands && isControlCommand && !commandAuthorized) {
+    return {
+      action: "block_unauthorized_command",
+      effectiveWasMentioned: false,
+      shouldBypassMention: false,
+    };
+  }
+
+  // ── Layer 3: mention 门控 + 命令旁路 ──
+  const mentionGate = resolveMentionGatingWithBypass({
+    requireMention,
+    canDetectMention,
+    wasMentioned,
+    implicitMention,
+    hasAnyMention,
+    allowTextCommands,
+    hasControlCommand: isControlCommand,
+    commandAuthorized,
+  });
+
+  if (mentionGate.shouldSkip) {
+    return {
+      action: "skip_no_mention",
+      effectiveWasMentioned: mentionGate.effectiveWasMentioned,
+      shouldBypassMention: mentionGate.shouldBypassMention,
+    };
+  }
+
+  return {
+    action: "pass",
+    effectiveWasMentioned: mentionGate.effectiveWasMentioned,
+    shouldBypassMention: mentionGate.shouldBypassMention,
+  };
+}

package/src/message-queue.ts

@@ -0,0 +1,349 @@
+import type { QueueSnapshot } from "./slash-commands.js";
+
+// ── 消息队列默认配置 ──
+const DEFAULT_GLOBAL_QUEUE_SIZE = 1000;
+const DEFAULT_PER_PEER_QUEUE_SIZE = 20;
+const DEFAULT_GROUP_QUEUE_SIZE = 50;
+const DEFAULT_MAX_CONCURRENT_USERS = 10;
+
+/**
+ * 消息队列项类型（用于异步处理消息，防止阻塞心跳）
+ */
+export interface QueuedMessage {
+  type: "c2c" | "guild" | "dm" | "group";
+  senderId: string;
+  senderName?: string;
+  content: string;
+  messageId: string;
+  timestamp: string;
+  channelId?: string;
+  guildId?: string;
+  groupOpenid?: string;
+  attachments?: Array<{ content_type: string; url: string; filename?: string; voice_wav_url?: string; asr_refer_text?: string }>;
+  /** 被引用消息的 refIdx（用户引用了哪条历史消息） */
+  refMsgIdx?: string;
+  /** 当前消息自身的 refIdx（供将来被引用） */
+  msgIdx?: string;
+  /** 事件类型（如 GROUP_AT_MESSAGE_CREATE），用于群消息合并时判断是否有 @ */
+  eventType?: string;
+  /** 发送者是否为机器人 */
+  senderIsBot?: boolean;
+  /** @ 提及列表（群消息合并时需要去重合并） */
+  mentions?: Array<{ scope?: "all" | "single"; id?: string; user_openid?: string; member_openid?: string; username?: string; bot?: boolean; is_you?: boolean }>;
+  /** 消息场景（来源、扩展字段） */
+  messageScene?: { source?: string; ext?: string[] };
+  /** 群消息合并标记：记录合并了多少条原始消息 */
+  _mergedCount?: number;
+  /** 合并前的原始消息列表（用于 gateway 侧逐条格式化信封） */
+  _mergedMessages?: QueuedMessage[];
+}
+
+export interface MessageQueueContext {
+  accountId: string;
+  log?: {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+    debug?: (msg: string) => void;
+  };
+  /** 外部提供的 abort 状态检查 */
+  isAborted: () => boolean;
+  /** 群聊队列上限（默认 50） */
+  groupQueueSize?: number;
+  /** 私聊/DM 队列上限（默认 20） */
+  peerQueueSize?: number;
+  /** 全局队列总量上限（默认 1000） */
+  globalQueueSize?: number;
+  /** 最大并发处理用户数（默认 10） */
+  maxConcurrentUsers?: number;
+}
+
+export interface MessageQueue {
+  enqueue: (msg: QueuedMessage) => void;
+  startProcessor: (handleMessageFn: (msg: QueuedMessage) => Promise<void>) => void;
+  getSnapshot: (senderPeerId: string) => QueueSnapshot;
+  getMessagePeerId: (msg: QueuedMessage) => string;
+  /** 清空指定用户的排队消息，返回被丢弃的消息数 */
+  clearUserQueue: (peerId: string) => number;
+  /** 立即执行一条消息（绕过队列），用于紧急命令 */
+  executeImmediate: (msg: QueuedMessage) => void;
+}
+
+// ── 群消息合并工具函数 ──
+
+/** 判断 peerId 是否属于群聊 */
+const isGroupPeer = (peerId: string): boolean =>
+  peerId.startsWith("group:") || peerId.startsWith("guild:");
+
+/**
+ * 将多条群消息合并为一条，用于群聊场景下排队消息的批量处理。
+ * - content 拼接为多行，每行带发送者前缀
+ * - 附件合并
+ * - messageId / msgIdx / timestamp 取最后一条（用于回复引用）
+ * - mentions 合并去重
+ * - 如果有任意一条 @了你（is_you），合并结果也标记 @你
+ * - senderIsBot 只要有一条不是 bot 就算非 bot
+ */
+function mergeGroupMessages(batch: QueuedMessage[]): QueuedMessage {
+  if (batch.length === 1) return batch[0];
+
+  const last = batch[batch.length - 1];
+  const first = batch[0];
+
+  // 拼接内容：每条消息带发送者前缀
+  const mergedContent = batch
+    .map((m) => {
+      const name = m.senderName ?? m.senderId;
+      return `[${name}]: ${m.content}`;
+    })
+    .join("\n");
+
+  // 合并附件
+  const mergedAttachments: QueuedMessage["attachments"] = [];
+  for (const m of batch) {
+    if (m.attachments?.length) {
+      mergedAttachments.push(...m.attachments);
+    }
+  }
+
+  // 合并 mentions（去重 by member_openid/id）
+  const seenMentionIds = new Set<string>();
+  const mergedMentions: NonNullable<QueuedMessage["mentions"]> = [];
+  let hasAtYouEvent = false;
+  for (const m of batch) {
+    if (m.eventType === "GROUP_AT_MESSAGE_CREATE") {
+      hasAtYouEvent = true;
+    }
+    if (m.mentions) {
+      for (const mt of m.mentions) {
+        const key = mt.member_openid ?? mt.id ?? mt.user_openid ?? "";
+        if (key && seenMentionIds.has(key)) continue;
+        if (key) seenMentionIds.add(key);
+        mergedMentions.push(mt);
+      }
+    }
+  }
+
+  // senderIsBot: 只要有一条来自非 bot 用户，就算非 bot
+  const allFromBot = batch.every((m) => m.senderIsBot);
+
+  return {
+    type: last.type,
+    senderId: last.senderId,
+    senderName: last.senderName,
+    senderIsBot: allFromBot,
+    content: mergedContent,
+    messageId: last.messageId,
+    timestamp: last.timestamp,
+    channelId: last.channelId,
+    guildId: last.guildId,
+    groupOpenid: last.groupOpenid,
+    attachments: mergedAttachments.length > 0 ? mergedAttachments : undefined,
+    refMsgIdx: first.refMsgIdx,
+    msgIdx: last.msgIdx,
+    eventType: hasAtYouEvent ? "GROUP_AT_MESSAGE_CREATE" : last.eventType,
+    mentions: mergedMentions.length > 0 ? mergedMentions : undefined,
+    messageScene: last.messageScene,
+    _mergedCount: batch.length,
+    _mergedMessages: batch.length > 1 ? batch : undefined,
+  };
+}
+
+/**
+ * 创建按用户并发的消息队列（同用户串行，跨用户并行）
+ *
+ * 内置群消息增强：
+ * - 群聊 / 私聊使用不同队列上限
+ * - 群聊溢出时优先丢弃 bot 消息
+ * - drain 时自动合并群聊排队消息（斜杠命令单独处理）
+ */
+export function createMessageQueue(ctx: MessageQueueContext): MessageQueue {
+  const { accountId, log } = ctx;
+  const globalQueueSize = ctx.globalQueueSize ?? DEFAULT_GLOBAL_QUEUE_SIZE;
+  const peerQueueSize = ctx.peerQueueSize ?? DEFAULT_PER_PEER_QUEUE_SIZE;
+  const groupQueueSize = ctx.groupQueueSize ?? DEFAULT_GROUP_QUEUE_SIZE;
+  const maxConcurrentUsers = ctx.maxConcurrentUsers ?? DEFAULT_MAX_CONCURRENT_USERS;
+
+  const userQueues = new Map<string, QueuedMessage[]>();
+  const activeUsers = new Set<string>();
+  let handleMessageFnRef: ((msg: QueuedMessage) => Promise<void>) | null = null;
+  let totalEnqueued = 0;
+
+  const getMessagePeerId = (msg: QueuedMessage): string => {
+    if (msg.type === "guild") return `guild:${msg.channelId ?? "unknown"}`;
+    if (msg.type === "group") return `group:${msg.groupOpenid ?? "unknown"}`;
+    return `dm:${msg.senderId}`;
+  };
+
+  /** 从满队列中淘汰一条消息（群聊优先丢弃 bot 消息，否则丢弃最旧） */
+  const evictOne = (queue: QueuedMessage[], isGroup: boolean): QueuedMessage | undefined => {
+    if (isGroup) {
+      const botIdx = queue.findIndex(m => m.senderIsBot);
+      if (botIdx >= 0) return queue.splice(botIdx, 1)[0];
+    }
+    return queue.shift();
+  };
+
+  /** 判断消息是否为斜杠指令 */
+  const isSlashCommand = (msg: QueuedMessage): boolean =>
+    (msg.content ?? "").trim().startsWith("/");
+
+  /** 处理单条消息，捕获异常并记录日志 */
+  const processOne = async (
+    msg: QueuedMessage,
+    peerId: string,
+    label: string,
+  ): Promise<boolean> => {
+    try {
+      await handleMessageFnRef!(msg);
+      return true;
+    } catch (err) {
+      log?.error(`[qqbot:${accountId}] ${label} error for ${peerId}: ${err}`);
+      return false;
+    }
+  };
+
+  /** 批量处理群聊排队消息：斜杠指令逐条处理，普通消息合并后处理 */
+  const drainGroupBatch = async (all: QueuedMessage[], peerId: string): Promise<void> => {
+    const commands: QueuedMessage[] = [];
+    const normal: QueuedMessage[] = [];
+    for (const m of all) {
+      (isSlashCommand(m) ? commands : normal).push(m);
+    }
+
+    // 指令消息逐条处理
+    for (const cmd of commands) {
+      log?.info(`[qqbot:${accountId}] Processing command independently for ${peerId}: ${(cmd.content ?? "").trim().slice(0, 50)}`);
+      await processOne(cmd, peerId, "Command processor");
+    }
+
+    // 普通消息合并后处理
+    if (normal.length > 0) {
+      const merged = mergeGroupMessages(normal);
+      if (normal.length > 1) {
+        log?.info(`[qqbot:${accountId}] Merged ${normal.length} queued group messages for ${peerId} into one`);
+      }
+      await processOne(merged, peerId, `Message processor (merged batch of ${normal.length})`);
+    }
+  };
+
+  /** 处理指定 peer 队列中的消息（串行） */
+  const drainUserQueue = async (peerId: string): Promise<void> => {
+    if (activeUsers.has(peerId)) return;
+    if (activeUsers.size >= maxConcurrentUsers) {
+      log?.info(`[qqbot:${accountId}] Max concurrent users (${maxConcurrentUsers}) reached, ${peerId} will wait`);
+      return;
+    }
+
+    const queue = userQueues.get(peerId);
+    if (!queue || queue.length === 0) {
+      userQueues.delete(peerId);
+      return;
+    }
+
+    activeUsers.add(peerId);
+    const isGroup = isGroupPeer(peerId);
+
+    try {
+      while (queue.length > 0 && !ctx.isAborted()) {
+        // 群聊排队 > 1 条：批量处理
+        if (isGroup && queue.length > 1 && handleMessageFnRef) {
+          const all = queue.splice(0, queue.length);
+          totalEnqueued = Math.max(0, totalEnqueued - all.length);
+          await drainGroupBatch(all, peerId);
+          continue;
+        }
+
+        // 非群聊 或 队列只剩 1 条：逐条处理
+        const msg = queue.shift()!;
+        totalEnqueued = Math.max(0, totalEnqueued - 1);
+        if (handleMessageFnRef) {
+          await processOne(msg, peerId, "Message processor");
+        }
+      }
+    } finally {
+      activeUsers.delete(peerId);
+      userQueues.delete(peerId);
+      // 尽量填满并发槽位
+      for (const [waitingPeerId, waitingQueue] of userQueues) {
+        if (activeUsers.size >= maxConcurrentUsers) break;
+        if (waitingQueue.length > 0 && !activeUsers.has(waitingPeerId)) {
+          drainUserQueue(waitingPeerId);
+        }
+      }
+    }
+  };
+
+  const enqueue = (msg: QueuedMessage): void => {
+    const peerId = getMessagePeerId(msg);
+    const isGroup = isGroupPeer(peerId);
+    let queue = userQueues.get(peerId);
+    if (!queue) {
+      queue = [];
+      userQueues.set(peerId, queue);
+    }
+
+    // 群聊和非群聊使用不同的队列上限
+    const maxSize = isGroup ? groupQueueSize : peerQueueSize;
+
+    // 队列溢出：淘汰一条旧消息
+    if (queue.length >= maxSize) {
+      const dropped = evictOne(queue, isGroup);
+      totalEnqueued = Math.max(0, totalEnqueued - 1);
+      if (isGroup && dropped?.senderIsBot) {
+        log?.info(`[qqbot:${accountId}] Queue full for ${peerId}, dropping bot message ${dropped.messageId}`);
+      } else {
+        log?.error(`[qqbot:${accountId}] Queue full for ${peerId}, dropping oldest message ${dropped?.messageId}`);
+      }
+    }
+
+    // 全局总量保护
+    totalEnqueued++;
+    if (totalEnqueued > globalQueueSize) {
+      log?.error(`[qqbot:${accountId}] Global queue limit reached (${totalEnqueued}), message from ${peerId} may be delayed`);
+    }
+
+    queue.push(msg);
+    log?.debug?.(`[qqbot:${accountId}] Message enqueued for ${peerId}, user queue: ${queue.length}, active users: ${activeUsers.size}`);
+
+    // 如果该用户没有正在处理的消息，立即启动处理
+    drainUserQueue(peerId);
+  };
+
+  const startProcessor = (handleMessageFn: (msg: QueuedMessage) => Promise<void>): void => {
+    handleMessageFnRef = handleMessageFn;
+    log?.info(`[qqbot:${accountId}] Message processor started (per-user concurrency, max ${maxConcurrentUsers} users)`);
+  };
+
+  const getSnapshot = (senderPeerId: string): QueueSnapshot => {
+    let totalPending = 0;
+    for (const [, q] of userQueues) {
+      totalPending += q.length;
+    }
+    const senderQueue = userQueues.get(senderPeerId);
+    return {
+      totalPending,
+      activeUsers: activeUsers.size,
+      maxConcurrentUsers,
+      senderPending: senderQueue ? senderQueue.length : 0,
+    };
+  };
+
+  const clearUserQueue = (peerId: string): number => {
+    const queue = userQueues.get(peerId);
+    if (!queue || queue.length === 0) return 0;
+    const droppedCount = queue.length;
+    queue.length = 0;
+    totalEnqueued = Math.max(0, totalEnqueued - droppedCount);
+    return droppedCount;
+  };
+
+  const executeImmediate = (msg: QueuedMessage): void => {
+    if (handleMessageFnRef) {
+      handleMessageFnRef(msg).catch(err => {
+        log?.error(`[qqbot:${accountId}] Immediate execution error: ${err}`);
+      });
+    }
+  };
+
+  return { enqueue, startProcessor, getSnapshot, getMessagePeerId, clearUserQueue, executeImmediate };
+}