@core-workspace/infoflow-openclaw-plugin 2026.3.8

package/src/logging.ts

@@ -0,0 +1,123 @@
+/**
+ * Structured logging module for Infoflow extension.
+ * Provides consistent logging interface across all Infoflow modules.
+ */
+
+import type { RuntimeLogger } from "openclaw/plugin-sdk";
+import { getInfoflowRuntime } from "./runtime.js";
+
+// ---------------------------------------------------------------------------
+// Logger Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a child logger with infoflow-specific bindings.
+ * Uses the PluginRuntime logging system for structured output.
+ */
+function createInfoflowLogger(module?: string): RuntimeLogger {
+  const runtime = getInfoflowRuntime();
+  const bindings: Record<string, unknown> = { subsystem: "gateway/channels/infoflow" };
+  if (module) {
+    bindings.module = module;
+  }
+  return runtime.logging.getChildLogger(bindings);
+}
+
+// ---------------------------------------------------------------------------
+// Module-specific Loggers (lazy initialization)
+// ---------------------------------------------------------------------------
+
+let _sendLog: RuntimeLogger | null = null;
+let _webhookLog: RuntimeLogger | null = null;
+let _botLog: RuntimeLogger | null = null;
+let _parseLog: RuntimeLogger | null = null;
+
+/**
+ * Logger for send operations (private/group message sending).
+ */
+export function getInfoflowSendLog(): RuntimeLogger {
+  if (!_sendLog) {
+    _sendLog = createInfoflowLogger("send");
+  }
+  return _sendLog;
+}
+
+/**
+ * Logger for webhook/monitor operations.
+ */
+export function getInfoflowWebhookLog(): RuntimeLogger {
+  if (!_webhookLog) {
+    _webhookLog = createInfoflowLogger("webhook");
+  }
+  return _webhookLog;
+}
+
+/**
+ * Logger for bot/message processing operations.
+ */
+export function getInfoflowBotLog(): RuntimeLogger {
+  if (!_botLog) {
+    _botLog = createInfoflowLogger("bot");
+  }
+  return _botLog;
+}
+
+/**
+ * Logger for request parsing operations.
+ */
+export function getInfoflowParseLog(): RuntimeLogger {
+  if (!_parseLog) {
+    _parseLog = createInfoflowLogger("parse");
+  }
+  return _parseLog;
+}
+
+// ---------------------------------------------------------------------------
+// Utility Functions
+// ---------------------------------------------------------------------------
+
+export type FormatErrorOptions = {
+  /** Include stack trace in the output (default: false) */
+  includeStack?: boolean;
+};
+
+/**
+ * Format error message for logging.
+ * @param err - The error to format
+ * @param options - Formatting options
+ */
+export function formatInfoflowError(err: unknown, options?: FormatErrorOptions): string {
+  if (err instanceof Error) {
+    if (options?.includeStack && err.stack) {
+      return err.stack;
+    }
+    return err.message;
+  }
+  return String(err);
+}
+
+/**
+ * Log a message when verbose mode is enabled.
+ * Checks shouldLogVerbose() via PluginRuntime, then writes to console for
+ * --verbose terminal output. Safe to call before runtime is initialized.
+ */
+export function logVerbose(message: string): void {
+  try {
+    if (!getInfoflowRuntime().logging.shouldLogVerbose()) return;
+    console.log(message);
+  } catch {
+    // runtime not available, skip verbose logging
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test-only exports (@internal)
+// ---------------------------------------------------------------------------
+
+/** @internal — Reset all cached loggers. Only use in tests. */
+export function _resetLoggers(): void {
+  _sendLog = null;
+  _webhookLog = null;
+  _botLog = null;
+  _parseLog = null;
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setInfoflowRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getInfoflowRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Infoflow runtime not initialized");
+  }
+  return runtime;
+}

package/src/security/dm-policy.ts

@@ -0,0 +1,80 @@
+/**
+ * Private chat (DM) security policy.
+ * Handles dmPolicy access control (open / pairing / allowlist).
+ */
+
+import type { ResolvedInfoflowAccount } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// DM policy check
+// ---------------------------------------------------------------------------
+
+export type DmPolicyResult =
+  | { allowed: true }
+  | { allowed: false; reason: "allowlist-rejected" }
+  | { allowed: true; note: "pairing" };
+
+/**
+ * Check if the sender is allowed to send private messages based on dmPolicy.
+ *
+ * - "open": all senders allowed
+ * - "pairing": allowed (pairing handled by the framework), note returned
+ * - "allowlist": only senders in allowFrom are allowed
+ */
+export function checkDmPolicy(
+  account: ResolvedInfoflowAccount,
+  fromuser: string,
+): DmPolicyResult {
+  const dmPolicy = account.config.dmPolicy ?? "open";
+
+  if (dmPolicy === "allowlist") {
+    const allowFrom = account.config.allowFrom ?? [];
+    if (!allowFrom.includes(fromuser)) {
+      return { allowed: false, reason: "allowlist-rejected" };
+    }
+  }
+
+  if (dmPolicy === "pairing") {
+    return { allowed: true, note: "pairing" };
+  }
+
+  return { allowed: true };
+}
+
+// ---------------------------------------------------------------------------
+// Group policy check
+// ---------------------------------------------------------------------------
+
+export type GroupPolicyResult =
+  | { allowed: true }
+  | { allowed: false; reason: "disabled" }
+  | { allowed: false; reason: "allowlist-rejected"; groupIdStr: string; wasMentioned: boolean };
+
+/**
+ * Check if the group is allowed to receive bot responses based on groupPolicy.
+ *
+ * - "open": all groups allowed
+ * - "disabled": no groups allowed
+ * - "allowlist": only groups in groupAllowFrom are allowed
+ */
+export function checkGroupPolicy(
+  account: ResolvedInfoflowAccount,
+  groupId: number | undefined,
+  wasMentioned: boolean,
+): GroupPolicyResult {
+  const groupPolicy = account.config.groupPolicy ?? "open";
+
+  if (groupPolicy === "disabled") {
+    return { allowed: false, reason: "disabled" };
+  }
+
+  if (groupPolicy === "allowlist") {
+    const groupAllowFrom = account.config.groupAllowFrom ?? [];
+    const groupIdStr = groupId != null ? String(groupId) : "";
+    if (!groupAllowFrom.includes(groupIdStr)) {
+      return { allowed: false, reason: "allowlist-rejected", groupIdStr, wasMentioned };
+    }
+  }
+
+  return { allowed: true };
+}

package/src/security/group-policy.ts

@@ -0,0 +1,271 @@
+/**
+ * Group chat security policy.
+ * Handles @mention detection, group access control, replyMode gating,
+ * follow-up window tracking, and conditional-reply prompt builders.
+ */
+
+import type {
+  InfoflowReplyMode,
+  InfoflowGroupConfig,
+  InfoflowMentionIds,
+  ResolvedInfoflowAccount,
+} from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Body item type (inbound group messages)
+// ---------------------------------------------------------------------------
+
+export type InfoflowBodyItem = {
+  type?: string;
+  content?: string;
+  label?: string;
+  /** 机器人 AT 时有此字段（数字），与 userid 互斥 */
+  robotid?: number;
+  /** AT 元素的显示名称 */
+  name?: string;
+  /** 人类用户 AT 时有此字段（uuap name），与 robotid 互斥 */
+  userid?: string;
+  /** IMAGE 类型 body item 的图片下载地址 */
+  downloadurl?: string;
+};
+
+// ---------------------------------------------------------------------------
+// @mention detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if the bot was @mentioned in the message body.
+ * Matches by robotName against the AT item's display name (case-insensitive).
+ */
+export function checkBotMentioned(bodyItems: InfoflowBodyItem[], robotName?: string): boolean {
+  if (!robotName) return false;
+  const normalizedRobotName = robotName.toLowerCase();
+  for (const item of bodyItems) {
+    if (item.type !== "AT") continue;
+    if (item.name?.toLowerCase() === normalizedRobotName) return true;
+  }
+  return false;
+}
+
+/**
+ * Check if any entry in the watchlist was @mentioned in the message body.
+ * Matching priority: userid > robotid (parsed as number) > name (fallback).
+ * Returns the matched ID (from watchMentions), or undefined if none matched.
+ */
+export function checkWatchMentioned(
+  bodyItems: InfoflowBodyItem[],
+  watchMentions: string[],
+): string | undefined {
+  if (!watchMentions.length) return undefined;
+  const normalizedIds = watchMentions.map((n) => n.toLowerCase());
+  const numericIds = watchMentions.map((n) => {
+    const num = Number(n);
+    return Number.isFinite(num) ? num : null;
+  });
+
+  for (const item of bodyItems) {
+    if (item.type !== "AT") continue;
+
+    if (item.userid) {
+      const idx = normalizedIds.indexOf(item.userid.toLowerCase());
+      if (idx !== -1) return watchMentions[idx];
+    }
+    if (item.robotid != null) {
+      const idx = numericIds.indexOf(item.robotid);
+      if (idx !== -1) return watchMentions[idx];
+    }
+    if (item.name) {
+      const idx = normalizedIds.indexOf(item.name.toLowerCase());
+      if (idx !== -1) return watchMentions[idx];
+    }
+  }
+  return undefined;
+}
+
+/** Check if message content matches the configured watchRegex regex pattern */
+export function checkWatchRegex(mes: string, pattern: string): boolean {
+  try {
+    return new RegExp(pattern, "i").test(mes);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extract non-bot mention IDs from inbound group message body items.
+ * Returns human userIds and robot agentIds (excluding the bot itself).
+ */
+export function extractMentionIds(
+  bodyItems: InfoflowBodyItem[],
+  robotName?: string,
+): InfoflowMentionIds {
+  const normalizedRobotName = robotName?.toLowerCase();
+  const userIds: string[] = [];
+  const agentIds: number[] = [];
+  const seenUsers = new Set<string>();
+  const seenAgents = new Set<number>();
+
+  for (const item of bodyItems) {
+    if (item.type !== "AT") continue;
+
+    if (item.robotid != null) {
+      if (normalizedRobotName && item.name?.toLowerCase() === normalizedRobotName) continue;
+      if (!seenAgents.has(item.robotid)) {
+        seenAgents.add(item.robotid);
+        agentIds.push(item.robotid);
+      }
+    } else if (item.userid) {
+      const key = item.userid.toLowerCase();
+      if (!seenUsers.has(key)) {
+        seenUsers.add(key);
+        userIds.push(item.userid);
+      }
+    }
+  }
+  return { userIds, agentIds };
+}
+
+// ---------------------------------------------------------------------------
+// Follow-up window tracking (in-memory)
+// ---------------------------------------------------------------------------
+
+/** In-memory map tracking bot's last reply timestamp per group */
+const groupLastReplyMap = new Map<string, number>();
+
+/** Record that the bot replied to a group */
+export function recordGroupReply(groupId: string): void {
+  groupLastReplyMap.set(groupId, Date.now());
+}
+
+/** Check if a group is within the follow-up window */
+export function isWithinFollowUpWindow(groupId: string, windowSeconds: number): boolean {
+  const lastReply = groupLastReplyMap.get(groupId);
+  if (!lastReply) return false;
+  return Date.now() - lastReply < windowSeconds * 1000;
+}
+
+// ---------------------------------------------------------------------------
+// Group config resolution
+// ---------------------------------------------------------------------------
+
+export type ResolvedGroupConfig = {
+  replyMode: InfoflowReplyMode;
+  followUp: boolean;
+  followUpWindow: number;
+  watchMentions: string[];
+  watchRegex?: string;
+  systemPrompt?: string;
+};
+
+/** Infer replyMode from legacy requireMention + watchMentions fields */
+export function inferLegacyReplyMode(account: ResolvedInfoflowAccount): InfoflowReplyMode {
+  const requireMention = account.config.requireMention !== false;
+  const hasWatch = (account.config.watchMentions ?? []).length > 0;
+  if (!requireMention) return "proactive";
+  if (hasWatch) return "mention-and-watch";
+  return "mention-only";
+}
+
+/** Resolve effective group config by merging group-level → account-level → legacy defaults */
+export function resolveGroupConfig(
+  account: ResolvedInfoflowAccount,
+  groupId?: number,
+): ResolvedGroupConfig {
+  const groupCfg: InfoflowGroupConfig | undefined =
+    groupId != null ? account.config.groups?.[String(groupId)] : undefined;
+  return {
+    replyMode: groupCfg?.replyMode ?? account.config.replyMode ?? inferLegacyReplyMode(account),
+    followUp: groupCfg?.followUp ?? account.config.followUp ?? true,
+    followUpWindow: groupCfg?.followUpWindow ?? account.config.followUpWindow ?? 300,
+    watchMentions: groupCfg?.watchMentions ?? account.config.watchMentions ?? [],
+    watchRegex: groupCfg?.watchRegex ?? account.config.watchRegex,
+    systemPrompt: groupCfg?.systemPrompt,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Conditional-reply prompt builders
+// ---------------------------------------------------------------------------
+
+function buildReplyJudgmentRules(): string {
+  return [
+    "# Rules",
+    "",
+    "## Can answer or help → Reply directly",
+    "",
+    "Reply if ANY of these apply:",
+    "- The question can be answered through common sense or logical reasoning (e.g. math, general knowledge)",
+    "- You can find relevant clues or content in your knowledge base, documentation, or code",
+    "- You have sufficient domain expertise to provide a valuable reference",
+    "",
+    "## Cannot answer → Reply with NO_REPLY only",
+    "",
+    "Do NOT reply if ANY of these apply:",
+    "- The message contains no clear question or request (e.g. casual chat, meaningless content)",
+    "- The question involves private information or context you have no knowledge of",
+    "- You cannot understand the core intent of the message",
+    "",
+    "# Response format",
+    "",
+    "- When you can answer: give a direct, concise answer. Do not explain why you chose to answer.",
+    "- When you cannot answer: output only NO_REPLY with no other text.",
+  ].join("\n");
+}
+
+/** GroupSystemPrompt for watch-mention triggered messages */
+export function buildWatchMentionPrompt(mentionedId: string): string {
+  return [
+    `Someone in the group @mentioned ${mentionedId}. As ${mentionedId}'s assistant, you observed this message.`,
+    "Decide whether you can answer on their behalf or provide help.",
+    "",
+    buildReplyJudgmentRules(),
+    "",
+    "# Examples",
+    "",
+    'Message: "What is 1+1?"',
+    "→ 2",
+    "",
+    'Message: "What is the qt parameter for search requests in the client code?"',
+    "(Assuming documentation records qt=s)",
+    "→ According to the documentation, the qt parameter for search requests is qt=s",
+    "",
+    'Message: "asdfghjkl random gibberish"',
+    "→ NO_REPLY",
+    "",
+    'Message: "Can you check today\'s release progress?"',
+    "(Assuming no relevant information available)",
+    "→ NO_REPLY",
+  ].join("\n");
+}
+
+/** GroupSystemPrompt for watch-content (regex) triggered messages */
+export function buildWatchRegexPrompt(pattern: string): string {
+  return [
+    `The message content matched the configured watch pattern (${pattern}).`,
+    "As the group assistant, you observed this message. Decide whether you can provide help or a valuable reply.",
+    "",
+    buildReplyJudgmentRules(),
+  ].join("\n");
+}
+
+/** GroupSystemPrompt for follow-up replies after bot's last response */
+export function buildFollowUpPrompt(): string {
+  return [
+    "You just replied to a message in this group. Someone has now sent a new message.",
+    "First determine if this message is a follow-up or continuation of the same topic you previously replied to, then decide if you can continue to help.",
+    "",
+    "Note: If this message is clearly a new topic or unrelated to your previous reply, respond with NO_REPLY.",
+    "",
+    buildReplyJudgmentRules(),
+  ].join("\n");
+}
+
+/** GroupSystemPrompt for proactive mode */
+export function buildProactivePrompt(): string {
+  return [
+    "You observed this message in the group. Decide whether you can provide help or a valuable reply.",
+    "If you need more context or clarification, you may ask follow-up questions.",
+    "",
+    buildReplyJudgmentRules(),
+  ].join("\n");
+}