@core-workspace/infoflow-openclaw-plugin 2026.3.8

package/src/handler/message-handler.ts

@@ -0,0 +1,801 @@
+import {
+  buildPendingHistoryContextFromMap,
+  clearHistoryEntriesIfEnabled,
+  DEFAULT_GROUP_HISTORY_LIMIT,
+  type HistoryEntry,
+  recordPendingHistoryEntryIfEnabled,
+  buildAgentMediaPayload,
+} from "openclaw/plugin-sdk";
+import { resolveInfoflowAccount } from "../channel/accounts.js";
+import { getInfoflowBotLog, formatInfoflowError, logVerbose } from "../logging.js";
+import { createInfoflowReplyDispatcher } from "../adapter/outbound/reply-dispatcher.js";
+import { sendInfoflowMessage } from "../channel/outbound.js";
+import { getInfoflowRuntime } from "../runtime.js";
+import {
+  checkBotMentioned,
+  checkWatchMentioned,
+  checkWatchRegex,
+  extractMentionIds,
+  recordGroupReply,
+  isWithinFollowUpWindow,
+  resolveGroupConfig,
+  buildWatchMentionPrompt,
+  buildWatchRegexPrompt,
+  buildFollowUpPrompt,
+  buildProactivePrompt,
+  type InfoflowBodyItem,
+} from "../security/group-policy.js";
+import { checkDmPolicy, checkGroupPolicy } from "../security/dm-policy.js";
+import type {
+  InfoflowChatType,
+  InfoflowMessageEvent,
+  InfoflowMentionIds,
+  InfoflowReplyMode,
+  InfoflowGroupConfig,
+  HandleInfoflowMessageParams,
+  HandlePrivateChatParams,
+  HandleGroupChatParams,
+  ResolvedInfoflowAccount,
+} from "../types.js";
+
+// Re-export types for external consumers
+export type { InfoflowChatType, InfoflowMessageEvent } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Group reply tracking (in-memory) for follow-up window
+// ---------------------------------------------------------------------------
+
+/** In-memory map accumulating recent group messages for context injection when bot is @mentioned */
+const chatHistories = new Map<string, HistoryEntry[]>();
+
+/**
+ * Handles an incoming private chat message from Infoflow.
+ * Receives the raw decrypted message data and dispatches to the agent.
+ */
+export async function handlePrivateChatMessage(params: HandlePrivateChatParams): Promise<void> {
+  const { cfg, msgData, accountId, statusSink } = params;
+
+  // Extract sender and content from msgData (flexible field names)
+  const fromuser = String(msgData.FromUserId ?? msgData.fromuserid ?? msgData.from ?? "");
+  const mes = String(msgData.Content ?? msgData.content ?? msgData.text ?? msgData.mes ?? "");
+
+  // Extract sender name (FromUserName is more human-readable than FromUserId)
+  const senderName = String(msgData.FromUserName ?? msgData.username ?? fromuser);
+
+  // Extract message ID for dedup tracking
+  const messageId = msgData.MsgId ?? msgData.msgid ?? msgData.messageid;
+  const messageIdStr = messageId != null ? String(messageId) : undefined;
+
+  // Extract timestamp (CreateTime is in seconds, convert to milliseconds)
+  const createTime = msgData.CreateTime ?? msgData.createtime;
+  const timestamp = createTime != null ? Number(createTime) * 1000 : Date.now();
+
+  // Detect image messages: MsgType=image with PicUrl
+  const msgType = String(msgData.MsgType ?? msgData.msgtype ?? "");
+  const picUrl = String(msgData.PicUrl ?? msgData.picurl ?? "");
+  const imageUrls: string[] = [];
+  if (msgType === "image" && picUrl.trim()) {
+    imageUrls.push(picUrl.trim());
+  }
+
+  logVerbose(
+    `[infoflow] private chat: fromuser=${fromuser}, senderName=${senderName}, mes=${mes}, msgType=${msgType}, raw msgData: ${JSON.stringify(msgData)}`,
+  );
+
+  logVerbose(
+    `[DEBUG private] content字段诊断: Content=${JSON.stringify(msgData.Content)}, content=${JSON.stringify(msgData.content)}, mes=${JSON.stringify(msgData.mes)}, MsgType=${JSON.stringify(msgData.MsgType)}, msgtype=${JSON.stringify(msgData.msgtype)}, PicUrl=${JSON.stringify(msgData.PicUrl)}, picurl=${JSON.stringify(msgData.picurl)}, imageUrls=${JSON.stringify(imageUrls)}`,
+  );
+
+  if (!fromuser || (!mes.trim() && imageUrls.length === 0)) {
+    return;
+  }
+
+  // Check dmPolicy: send a hint when user is not authorized
+  const account = resolveInfoflowAccount({ cfg, accountId });
+  const dmResult = checkDmPolicy(account, fromuser);
+  if (!dmResult.allowed) {
+    logVerbose(`[infoflow] private message rejected: dmPolicy=allowlist, fromuser=${fromuser}`);
+    sendInfoflowMessage({
+      cfg,
+      to: fromuser,
+      contents: [{ type: "text", content: "🚫 抱歉，您暂无使用权限，请联系龙虾主开通～" }],
+      accountId: account.accountId,
+    }).catch(() => { /* ignore send errors */ });
+    return;
+  }
+  if ("note" in dmResult && dmResult.note === "pairing") {
+    // pairing 由框架处理配对逻辑，此处仅做日志，不发提示以免干扰配对流程
+    logVerbose(`[infoflow] private message: dmPolicy=pairing, fromuser=${fromuser}`);
+  }
+
+  // For image-only messages (no text), use placeholder
+  let effectiveMes = mes.trim();
+  if (!effectiveMes && imageUrls.length > 0) {
+    effectiveMes = "<media:image>";
+  }
+
+  // Delegate to the common message handler (private chat)
+  await handleInfoflowMessage({
+    cfg,
+    event: {
+      fromuser,
+      mes: effectiveMes,
+      chatType: "direct",
+      senderName,
+      messageId: messageIdStr,
+      timestamp,
+      imageUrls: imageUrls.length > 0 ? imageUrls : undefined,
+    },
+    accountId,
+    statusSink,
+  });
+}
+
+/**
+ * Handles an incoming group chat message from Infoflow.
+ * Receives the raw decrypted message data and dispatches to the agent.
+ */
+export async function handleGroupChatMessage(params: HandleGroupChatParams): Promise<void> {
+  const { cfg, msgData, accountId, statusSink } = params;
+
+  // Extract sender from nested structure or flat fields
+  const header = (msgData.message as Record<string, unknown>)?.header as
+    | Record<string, unknown>
+    | undefined;
+  const fromuser = String(header?.fromuserid ?? msgData.fromuserid ?? msgData.from ?? "");
+
+  // Extract sender's imid (数字ID) - the numeric user ID is in msgData.fromid
+  const senderImid = msgData.fromid ?? header?.imid ?? header?.fromimid ?? msgData.imid ?? msgData.fromimid;
+  const senderImidStr = senderImid != null ? String(senderImid) : undefined;
+
+  // Extract message ID (priority: header.messageid > header.msgid > MsgId)
+  const messageId = header?.messageid ?? header?.msgid ?? msgData.MsgId;
+  const messageIdStr = messageId != null ? String(messageId) : undefined;
+
+  const rawGroupId = msgData.groupid ?? header?.groupid;
+  const groupid =
+    typeof rawGroupId === "number" ? rawGroupId : rawGroupId ? Number(rawGroupId) : undefined;
+
+  // Extract timestamp (time is in milliseconds)
+  const rawTime = msgData.time ?? header?.servertime;
+  const timestamp = rawTime != null ? Number(rawTime) : Date.now();
+
+  // Debug: 打印完整的原始消息数据
+  logVerbose(`[DEBUG bot.groupchat] 完整 msgData: ${JSON.stringify(msgData, null, 2)}`);
+  logVerbose(`[DEBUG bot.groupchat] 完整 header: ${JSON.stringify(header, null, 2)}`);
+
+  // Debug: 输出所有可能的 ID 字段
+  logVerbose(`[DEBUG bot.groupchat] 查找 imid (期望值: 102752365):`);
+  logVerbose(`  - header.imid: ${header?.imid}`);
+  logVerbose(`  - header.fromimid: ${header?.fromimid}`);
+  logVerbose(`  - header.fromuserid: ${header?.fromuserid}`);
+  logVerbose(`  - msgData.imid: ${msgData.imid}`);
+  logVerbose(`  - msgData.fromimid: ${msgData.fromimid}`);
+  logVerbose(`  - msgData.fromuserid: ${msgData.fromuserid}`);
+  logVerbose(`  - msgData.from: ${msgData.from}`);
+  logVerbose(`  - msgData.userid: ${msgData.userid}`);
+  logVerbose(`  - fromuser: ${fromuser}`);
+  logVerbose(`  - senderImidStr: ${senderImidStr}`);
+
+  if (!fromuser) {
+    return;
+  }
+
+  // Extract message content from body array or flat content field
+  const message = msgData.message as Record<string, unknown> | undefined;
+  const bodyItems = (message?.body ?? msgData.body ?? []) as InfoflowBodyItem[];
+
+  // Resolve account to get robotName for mention detection
+  const account = resolveInfoflowAccount({ cfg, accountId });
+  const robotName = account.config.robotName;
+
+  // Check groupPolicy allowlist
+  const wasMentionedEarly = checkBotMentioned(bodyItems, robotName);
+  const groupPolicyResult = checkGroupPolicy(account, groupid, wasMentionedEarly);
+  if (!groupPolicyResult.allowed) {
+    if (groupPolicyResult.reason === "disabled") {
+      logVerbose(`[infoflow] group message rejected: groupPolicy=disabled`);
+    } else {
+      logVerbose(`[infoflow] group message rejected: group=${groupPolicyResult.groupIdStr} not in groupAllowFrom`);
+      // 发送无权限提示，仅当消息是 @机器人 时才回复，避免在无关群里刷屏
+      if (groupPolicyResult.wasMentioned && groupPolicyResult.groupIdStr) {
+        sendInfoflowMessage({
+          cfg,
+          to: `group:${groupPolicyResult.groupIdStr}`,
+          contents: [{ type: "text", content: "🚫 抱歉，该群暂无使用权限，请联系龙虾主开通～" }],
+          accountId: account.accountId,
+        }).catch(() => { /* ignore send errors */ });
+      }
+    }
+    return;
+  }
+
+  // Check if bot was @mentioned (by robotName)
+  const wasMentioned = wasMentionedEarly;
+
+  // Extract non-bot mention IDs (userIds + agentIds) for LLM-driven @mentions
+  const mentionIds = extractMentionIds(bodyItems, robotName);
+
+  // Build two versions: mes (for CommandBody, no @xxx) and rawMes (for RawBody, with @xxx)
+  let textContent = "";
+  let rawTextContent = "";
+  const replyContextItems: string[] = [];
+  const imageUrls: string[] = [];
+  if (Array.isArray(bodyItems)) {
+    for (const item of bodyItems) {
+      if (item.type === "replyData") {
+        // 引用回复：提取被引用消息的内容（可能有多条引用）
+        const replyBody = (item.content ?? "").trim();
+        if (replyBody) {
+          replyContextItems.push(replyBody);
+        }
+      } else if (item.type === "TEXT") {
+        textContent += item.content ?? "";
+        rawTextContent += item.content ?? "";
+      } else if (item.type === "LINK") {
+        const label = item.label ?? "";
+        if (label) {
+          textContent += ` ${label} `;
+          rawTextContent += ` ${label} `;
+        }
+      } else if (item.type === "AT") {
+        // AT elements only go into rawTextContent, not textContent
+        const name = item.name ?? "";
+        if (name) {
+          rawTextContent += `@${name} `;
+        }
+      } else if (item.type === "IMAGE") {
+        // 提取图片下载地址
+        logVerbose(`[DEBUG bot.groupchat] IMAGE item: ${JSON.stringify(item, null, 2)}`);
+        const url = item.downloadurl;
+        if (typeof url === "string" && url.trim()) {
+          logVerbose(`[DEBUG bot.groupchat] 提取到图片URL: ${url}`);
+          imageUrls.push(url.trim());
+        } else {
+          logVerbose(`[DEBUG bot.groupchat] WARNING: IMAGE item 缺少有效的 downloadurl 字段`);
+        }
+      }
+    }
+  }
+
+  let mes = textContent.trim() || String(msgData.content ?? msgData.text ?? "");
+  const rawMes = rawTextContent.trim() || mes;
+
+  const replyContext = replyContextItems.length > 0 ? replyContextItems : undefined;
+
+  if (!mes && !replyContext && imageUrls.length === 0) {
+    return;
+  }
+  // 纯图片消息：设置占位符
+  if (!mes && imageUrls.length > 0) {
+    logVerbose(`[DEBUG bot.groupchat] 纯图片消息: ${imageUrls.length} 张图片`);
+    mes = `<media:image>${imageUrls.length > 1 ? ` (${imageUrls.length} images)` : ""}`;
+  }
+  // If mes is empty but replyContext exists, use a placeholder so the message is not dropped
+  if (!mes && replyContext) {
+    mes = "(引用回复)";
+  }
+
+  // Extract sender name from header or fallback to fromuser
+  const senderName = String(header?.username ?? header?.nickname ?? msgData.username ?? fromuser);
+
+  // Delegate to the common message handler (group chat)
+  await handleInfoflowMessage({
+    cfg,
+    event: {
+      fromuser,
+      mes,
+      rawMes,
+      chatType: "group",
+      groupId: groupid,
+      senderName,
+      wasMentioned,
+      messageId: messageIdStr,
+      timestamp,
+      bodyItems,
+      mentionIds:
+        mentionIds.userIds.length > 0 || mentionIds.agentIds.length > 0 ? mentionIds : undefined,
+      replyContext,
+      imageUrls: imageUrls.length > 0 ? imageUrls : undefined,
+      senderImid: senderImidStr,  // 传递发送者的 imid
+    },
+    accountId,
+    statusSink,
+  });
+}
+
+/**
+ * Resolves route, builds envelope, records session meta, and dispatches reply for one incoming Infoflow message.
+ * Called from monitor after webhook request is validated.
+ */
+export async function handleInfoflowMessage(params: HandleInfoflowMessageParams): Promise<void> {
+  const { cfg, event, accountId, statusSink } = params;
+  const { fromuser, mes, chatType, groupId, senderName } = event;
+
+  const account = resolveInfoflowAccount({ cfg, accountId });
+  const core = getInfoflowRuntime();
+
+  const isGroup = chatType === "group";
+  // Convert groupId (number) to string for peerId since routing expects string
+  const peerId = isGroup ? (groupId !== undefined ? String(groupId) : fromuser) : fromuser;
+
+  // Resolve per-group config for replyMode gating
+  const groupCfg = isGroup ? resolveGroupConfig(account, groupId) : undefined;
+
+  // "ignore" mode: discard immediately, no save, no think, no reply
+  if (isGroup && groupCfg?.replyMode === "ignore") {
+    return;
+  }
+
+  // Resolve route based on chat type
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg,
+    channel: "infoflow",
+    accountId: account.accountId,
+    peer: {
+      kind: isGroup ? "group" : "direct",
+      id: peerId,
+    },
+  });
+
+  const storePath = core.channel.session.resolveStorePath(cfg.session?.store, {
+    agentId: route.agentId,
+  });
+  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
+  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey: route.sessionKey,
+  });
+
+  // Build conversation label and from address based on chat type
+  const fromLabel = isGroup ? `group:${groupId}` : senderName || fromuser;
+  const fromAddress = isGroup ? `infoflow:group:${groupId}` : `infoflow:${fromuser}`;
+  const toAddress = isGroup ? `infoflow:group:${groupId}` : `infoflow:${fromuser}`;
+
+  const body = core.channel.reply.formatAgentEnvelope({
+    channel: "Infoflow",
+    from: fromLabel,
+    timestamp: Date.now(),
+    previousTimestamp,
+    envelope: envelopeOptions,
+    body: mes,
+  });
+
+  // Inject accumulated group chat history into the body for context
+  const historyKey = isGroup && groupId !== undefined ? String(groupId) : undefined;
+  let combinedBody = body;
+  if (isGroup && historyKey) {
+    combinedBody = buildPendingHistoryContextFromMap({
+      historyMap: chatHistories,
+      historyKey,
+      limit: DEFAULT_GROUP_HISTORY_LIMIT,
+      currentMessage: body,
+      formatEntry: (entry) =>
+        core.channel.reply.formatAgentEnvelope({
+          channel: "Infoflow",
+          from: entry.sender,
+          timestamp: entry.timestamp ?? Date.now(),
+          body: entry.body,
+        }),
+    });
+  }
+
+  const inboundHistory =
+    isGroup && historyKey
+      ? (chatHistories.get(historyKey) ?? []).map((e) => ({
+          sender: e.sender,
+          body: e.body,
+          timestamp: e.timestamp,
+        }))
+      : undefined;
+
+  // --- Resolve inbound media (images) ---
+  const INFOFLOW_MAX_IMAGES = 20;
+  const mediaMaxBytes = 30 * 1024 * 1024; // 30MB default, matching Feishu
+  const mediaList: Array<{ path: string; contentType?: string }> = [];
+  const failReasons: string[] = [];
+
+  logVerbose(`[DEBUG bot] 图片处理开始: imageUrls数量=${event.imageUrls?.length ?? 0}`);
+  if (event.imageUrls && event.imageUrls.length > 0) {
+    logVerbose(`[DEBUG bot] 待下载图片URLs: ${JSON.stringify(event.imageUrls)}`);
+    // Collect unique hostnames from image URLs for SSRF allowlist.
+    // Infoflow image servers (e.g. xp2.im.baidu.com, e4hi.im.baidu.com) resolve to
+    // internal IPs on Baidu's network, so they need to be explicitly allowed.
+    const allowedHostnames: string[] = [];
+    for (const imageUrl of event.imageUrls) {
+      try {
+        const hostname = new URL(imageUrl).hostname;
+        if (hostname && !allowedHostnames.includes(hostname)) {
+          allowedHostnames.push(hostname);
+        }
+      } catch {
+        // invalid URL, will fail at fetch time
+      }
+    }
+    const ssrfPolicy = allowedHostnames.length > 0 ? { allowedHostnames } : undefined;
+
+    const urls = event.imageUrls.slice(0, INFOFLOW_MAX_IMAGES);
+    const results = await Promise.allSettled(
+      urls.map(async (imageUrl) => {
+        logVerbose(`[DEBUG bot] 开始下载图片: ${imageUrl}`);
+        const fetched = await core.channel.media.fetchRemoteMedia({
+          url: imageUrl,
+          maxBytes: mediaMaxBytes,
+          ssrfPolicy,
+        });
+        logVerbose(`[DEBUG bot] 图片下载成功: size=${fetched.buffer.length}, contentType=${fetched.contentType}`);
+        const saved = await core.channel.media.saveMediaBuffer(
+          fetched.buffer,
+          fetched.contentType ?? undefined,
+          "inbound",
+          mediaMaxBytes,
+        );
+        logVerbose(`[infoflow] downloaded image from ${imageUrl}, saved to ${saved.path}`);
+        logVerbose(`[DEBUG bot] 图片保存成功: path=${saved.path}`);
+        return { path: saved.path, contentType: saved.contentType ?? fetched.contentType };
+      }),
+    );
+    for (const result of results) {
+      if (result.status === "fulfilled") {
+        mediaList.push(result.value);
+        logVerbose(`[DEBUG bot] 图片处理成功: ${result.value.path}`);
+      } else {
+        const reason = String(result.reason);
+        logVerbose(`[infoflow] failed to download image: ${reason}`);
+        logVerbose(`[DEBUG bot] 图片下载失败: ${reason}`);
+        failReasons.push(reason);
+      }
+    }
+  }
+
+  logVerbose(`[DEBUG bot] 图片处理完成: 成功=${mediaList.length}, 失败=${failReasons.length}`);
+
+  const mediaPayload = buildAgentMediaPayload(mediaList);
+
+  // If user sent images but some/all downloads failed, adjust the body to inform the LLM.
+  const requestedImageCount = event.imageUrls?.length ?? 0;
+  const downloadedImageCount = mediaList.length;
+  const failedImageCount = requestedImageCount - downloadedImageCount;
+  if (requestedImageCount > 0 && failedImageCount > 0) {
+    // Deduplicate error reasons and truncate for readability
+    const uniqueReasons = [...new Set(failReasons)];
+    const reasonSummary = uniqueReasons.map((r) => r.slice(0, 200)).join("; ");
+
+    if (downloadedImageCount === 0) {
+      // All failed
+      const failNote =
+        `[The user sent ${requestedImageCount > 1 ? `${requestedImageCount} images` : "an image"}, ` +
+        `but failed to load: ${reasonSummary}]`;
+      if (combinedBody.includes("<media:image>")) {
+        combinedBody = combinedBody.replace(/<media:image>(\s*\(\d+ images\))?/, failNote);
+      } else {
+        combinedBody += `\n\n${failNote}`;
+      }
+    } else {
+      // Partial failure: some images loaded, some didn't
+      const failNote = `[${failedImageCount} of ${requestedImageCount} images failed to load: ${reasonSummary}]`;
+      combinedBody += `\n\n${failNote}`;
+    }
+  }
+
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: combinedBody,
+    RawBody: event.rawMes ?? mes,
+    CommandBody: mes,
+    From: fromAddress,
+    To: toAddress,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: chatType,
+    ConversationLabel: fromLabel,
+    GroupSubject: isGroup ? `group:${groupId}` : undefined,
+    SenderName: senderName || fromuser,
+    SenderId: fromuser,
+    Provider: "infoflow",
+    Surface: "infoflow",
+    MessageSid: event.messageId ?? `${Date.now()}`,
+    Timestamp: event.timestamp ?? Date.now(),
+    OriginatingChannel: "infoflow",
+    OriginatingTo: toAddress,
+    WasMentioned: isGroup ? event.wasMentioned : undefined,
+    ReplyToBody: event.replyContext ? event.replyContext.join("\n---\n") : undefined,
+    InboundHistory: inboundHistory,
+    CommandAuthorized: true,
+    ...mediaPayload,
+  });
+
+  // Record session using recordInboundSession for proper session tracking
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (err) => {
+      getInfoflowBotLog().error(
+        `[infoflow] failed updating session meta (sessionKey=${route.sessionKey}, accountId=${accountId}): ${formatInfoflowError(err)}`,
+      );
+    },
+  });
+
+  // Reply mode gating for group messages
+  // Session is already recorded above for context history
+  let triggerReason = "direct-message";
+  if (isGroup && groupCfg) {
+    const { replyMode } = groupCfg;
+    const groupIdStr = groupId !== undefined ? String(groupId) : undefined;
+
+    // "record" mode: save to session only, no think, no reply
+    if (replyMode === "record") {
+      if (groupIdStr) {
+        logVerbose(
+          `[infoflow:bot] pending: from=${fromuser}, group=${groupId}, reason=record-mode`,
+        );
+        recordPendingHistoryEntryIfEnabled({
+          historyMap: chatHistories,
+          historyKey: groupIdStr,
+          entry: { sender: senderName || fromuser, body: mes, timestamp: Date.now() },
+          limit: DEFAULT_GROUP_HISTORY_LIMIT,
+        });
+      }
+      return;
+    }
+
+    const canDetectMention = Boolean(account.config.robotName);
+    const wasMentioned = event.wasMentioned === true;
+
+    if (replyMode === "mention-only") {
+      // Only reply if bot was @mentioned
+      const shouldReply = canDetectMention && wasMentioned;
+      if (shouldReply) {
+        triggerReason = "bot-mentioned";
+      } else {
+        // Check follow-up window: if bot recently replied, allow LLM to decide
+        if (
+          groupCfg.followUp &&
+          groupIdStr &&
+          isWithinFollowUpWindow(groupIdStr, groupCfg.followUpWindow)
+        ) {
+          triggerReason = "followUp";
+          ctxPayload.GroupSystemPrompt = buildFollowUpPrompt();
+        } else {
+          if (groupIdStr) {
+            logVerbose(
+              `[infoflow:bot] pending: from=${fromuser}, group=${groupId}, reason=mention-only-not-mentioned`,
+            );
+            recordPendingHistoryEntryIfEnabled({
+              historyMap: chatHistories,
+              historyKey: groupIdStr,
+              entry: { sender: senderName || fromuser, body: mes, timestamp: Date.now() },
+              limit: DEFAULT_GROUP_HISTORY_LIMIT,
+            });
+          }
+          return;
+        }
+      }
+    } else if (replyMode === "mention-and-watch") {
+      // Reply if bot @mentioned, or if watched person @mentioned, or follow-up
+      const botMentioned = canDetectMention && wasMentioned;
+      if (botMentioned) {
+        triggerReason = "bot-mentioned";
+      } else {
+        // Check watch-mention
+        const watchMentions = groupCfg.watchMentions;
+        const matchedWatchId =
+          watchMentions.length > 0 && event.bodyItems
+            ? checkWatchMentioned(event.bodyItems, watchMentions)
+            : undefined;
+
+        if (matchedWatchId) {
+          triggerReason = `watchMentions(${matchedWatchId})`;
+          // Watch-mention triggered: instruct agent to reply only if confident
+          ctxPayload.GroupSystemPrompt = buildWatchMentionPrompt(matchedWatchId);
+        } else if (groupCfg.watchRegex && checkWatchRegex(mes, groupCfg.watchRegex)) {
+          triggerReason = `watchRegex(${groupCfg.watchRegex})`;
+          // Watch-content triggered: message matched configured regex pattern
+          ctxPayload.GroupSystemPrompt = buildWatchRegexPrompt(groupCfg.watchRegex);
+        } else if (
+          groupCfg.followUp &&
+          groupIdStr &&
+          isWithinFollowUpWindow(groupIdStr, groupCfg.followUpWindow)
+        ) {
+          triggerReason = "followUp";
+          // Follow-up window: let LLM decide if this is a follow-up
+          ctxPayload.GroupSystemPrompt = buildFollowUpPrompt();
+        } else {
+          if (groupIdStr) {
+            logVerbose(
+              `[infoflow:bot] pending: from=${fromuser}, group=${groupId}, reason=mention-and-watch-no-trigger`,
+            );
+            recordPendingHistoryEntryIfEnabled({
+              historyMap: chatHistories,
+              historyKey: groupIdStr,
+              entry: { sender: senderName || fromuser, body: mes, timestamp: Date.now() },
+              limit: DEFAULT_GROUP_HISTORY_LIMIT,
+            });
+          }
+          return;
+        }
+      }
+    } else if (replyMode === "proactive") {
+      // Always think and potentially reply
+      const botMentioned = canDetectMention && wasMentioned;
+      if (botMentioned) {
+        triggerReason = "bot-mentioned";
+      } else {
+        // Check watch-mention first (higher priority prompt)
+        const watchMentions = groupCfg.watchMentions;
+        const matchedWatchId =
+          watchMentions.length > 0 && event.bodyItems
+            ? checkWatchMentioned(event.bodyItems, watchMentions)
+            : undefined;
+        if (matchedWatchId) {
+          triggerReason = `watchMentions(${matchedWatchId})`;
+          ctxPayload.GroupSystemPrompt = buildWatchMentionPrompt(matchedWatchId);
+        } else {
+          triggerReason = "proactive";
+          ctxPayload.GroupSystemPrompt = buildProactivePrompt();
+        }
+      }
+    }
+
+    // Inject per-group systemPrompt (append, don't replace)
+    if (groupCfg.systemPrompt) {
+      const existing = ctxPayload.GroupSystemPrompt ?? "";
+      ctxPayload.GroupSystemPrompt = existing
+        ? `${existing}\n\n---\n\n${groupCfg.systemPrompt}`
+        : groupCfg.systemPrompt;
+    }
+  }
+
+  // Build unified target: "group:<id>" for group chat, username for private chat
+  const to = isGroup && groupId !== undefined ? `group:${groupId}` : fromuser;
+
+  // Provide mention context to the LLM so it can decide who to @mention
+  if (isGroup && event.mentionIds) {
+    const parts: string[] = [];
+    if (event.mentionIds.userIds.length > 0) {
+      parts.push(`User IDs: ${event.mentionIds.userIds.join(", ")}`);
+    }
+    if (event.mentionIds.agentIds.length > 0) {
+      parts.push(`Bot IDs: ${event.mentionIds.agentIds.join(", ")}`);
+    }
+    if (parts.length > 0) {
+      ctxPayload.Body += `\n\n[System: @mentioned in group: ${parts.join("; ")}. To @mention someone in your reply, use the @id format]`;
+    }
+  }
+
+  logVerbose(
+    `[infoflow:bot] dispatching to LLM: from=${fromuser}, group=${groupId ?? "N/A"}, trigger=${triggerReason}, replyMode=${groupCfg?.replyMode ?? "N/A"}`,
+  );
+
+  // Debug: Log reply-to context
+  logVerbose(`[DEBUG bot] event.messageId=${event.messageId}, event.senderImid=${event.senderImid}, isGroup=${isGroup}, mes=${mes.slice(0, 50)}`);
+  if (!event.messageId) {
+    logVerbose(`[DEBUG bot] WARNING: event.messageId is undefined/null!`);
+  }
+  if (!event.senderImid) {
+    logVerbose(`[DEBUG bot] WARNING: event.senderImid is undefined/null!`);
+  }
+  if (!isGroup) {
+    logVerbose(`[DEBUG bot] Not a group message, skipping reply-to`);
+  }
+
+  // Send "processing" hint if LLM takes longer than processingHintDelay seconds
+  // (default: 5s). Gives users feedback without spamming fast responses.
+  const processingHintEnabled = account.config.processingHint !== false;
+  let cancelProcessingHint: (() => void) | undefined;
+  let hintWasSent = false;
+  const dispatchStartTime = Date.now();
+  if (processingHintEnabled) {
+    const delayMs = (account.config.processingHintDelay ?? 5) * 1000;
+    const processingReplyTo =
+      isGroup && event.messageId
+        ? {
+            messageid: event.messageId,
+            preview: mes ? (mes.length > 100 ? mes.slice(0, 100) + "..." : mes) : "",
+            ...(event.senderImid ? { imid: event.senderImid } : {}),
+            replytype: "2" as const,
+          }
+        : undefined;
+    let cancelled = false;
+    cancelProcessingHint = () => { cancelled = true; };
+    setTimeout(() => {
+      if (cancelled) return;
+      hintWasSent = true;
+      sendInfoflowMessage({
+        cfg,
+        to,
+        contents: [{ type: "text", content: "⏳ 处理中..." }],
+        accountId: account.accountId,
+        replyTo: processingReplyTo,
+      }).catch(() => {});
+    }, delayMs);
+  }
+
+  const { dispatcherOptions, replyOptions } = createInfoflowReplyDispatcher({
+    cfg,
+    agentId: route.agentId,
+    accountId: account.accountId,
+    to,
+    statusSink,
+    // @mention the sender back when bot was directly @mentioned in a group
+    atOptions: isGroup && event.wasMentioned ? { atUserIds: [fromuser] } : undefined,
+    // Pass mention IDs for LLM-driven @mention resolution in outbound text
+    mentionIds: isGroup ? event.mentionIds : undefined,
+    // Pass inbound messageId for outbound reply-to (group only)
+    replyToMessageId: isGroup ? event.messageId : undefined,
+    replyToPreview: isGroup ? mes : undefined,
+    replyToImid: isGroup ? event.senderImid : undefined,
+    // Message format: per-chat-type config, falling back to "text"
+    messageFormat: isGroup
+      ? (account.config.groupMessageFormat ?? "text")
+      : (account.config.dmMessageFormat ?? "text"),
+  });
+
+  // Cancel processing hint the moment the first real message starts being delivered,
+  // so the hint never appears after the bot's actual reply.
+  if (cancelProcessingHint) {
+    const originalDeliver = dispatcherOptions.deliver;
+    let hintCancelledOnDeliver = false;
+    dispatcherOptions.deliver = async (payload: Parameters<typeof originalDeliver>[0]) => {
+      if (!hintCancelledOnDeliver) {
+        hintCancelledOnDeliver = true;
+        cancelProcessingHint!();
+      }
+      return originalDeliver(payload);
+    };
+  }
+
+  const dispatchResult = await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg,
+    dispatcherOptions,
+    replyOptions,
+  });
+
+  // Fallback cancel: in case deliver was never called (e.g. empty response)
+  cancelProcessingHint?.();
+
+  // If hint was shown to the user, send "搞定" so they know the task is done
+  if (hintWasSent) {
+    const elapsedSec = Math.round((Date.now() - dispatchStartTime) / 1000);
+    sendInfoflowMessage({
+      cfg,
+      to,
+      contents: [{ type: "text", content: `任务完成 ✨ (${elapsedSec}s)` }],
+      accountId: account.accountId,
+    }).catch(() => {});
+  }
+
+  const didReply = dispatchResult?.queuedFinal ?? false;
+
+  // Clear accumulated history after dispatch (it's now in the session transcript)
+  if (isGroup && historyKey) {
+    clearHistoryEntriesIfEnabled({
+      historyMap: chatHistories,
+      historyKey,
+      limit: DEFAULT_GROUP_HISTORY_LIMIT,
+    });
+  }
+
+  // Record bot reply timestamp for follow-up window tracking
+  if (didReply && isGroup && groupId !== undefined) {
+    recordGroupReply(String(groupId));
+  }
+
+  logVerbose(
+    `[infoflow] dispatch complete: ${chatType} from ${fromuser}, replied=${didReply}, finalCount=${dispatchResult?.counts.final ?? 0}, hasGroupSystemPrompt=${Boolean(ctxPayload.GroupSystemPrompt)}`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Test-only exports (@internal)
+// ---------------------------------------------------------------------------
+
+/** @internal — Check if bot was mentioned in message body. Only exported for tests. */
+export { checkBotMentioned as _checkBotMentioned } from "../security/group-policy.js";
+
+/** @internal — Check if any watch-list name was @mentioned. Only exported for tests. */
+export { checkWatchMentioned as _checkWatchMentioned } from "../security/group-policy.js";
+
+/** @internal — Extract non-bot mention IDs. Only exported for tests. */
+export { extractMentionIds as _extractMentionIds } from "../security/group-policy.js";