@core-workspace/infoflow-openclaw-plugin 2026.3.8

package/src/tools/index.ts

@@ -0,0 +1,277 @@
+/**
+ * Infoflow Agent Tools（Agent 工具注册）
+ *
+ * 向 OpenClaw 注册两个供 LLM function calling 使用的工具：
+ *   - infoflow_send:   主动向用户或群发送消息
+ *   - infoflow_recall: 撤回近期发送的消息
+ *
+ * 这两个工具封装了 outbound/send.ts 中的底层发送/撤回逻辑，
+ * 让 Agent 能够主动发消息，而不仅限于被动回复。
+ */
+
+import { Type, type Static } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { resolveInfoflowAccount } from "../channel/accounts.js";
+import { logVerbose } from "../logging.js";
+import { sendInfoflowMessage, recallInfoflowGroupMessage, recallInfoflowPrivateMessage } from "../channel/outbound.js";
+import { querySentMessages, removeRecalledMessages } from "../utils/store/message-store.js";
+import { normalizeInfoflowTarget } from "../adapter/outbound/target-resolver.js";
+
+// ---------------------------------------------------------------------------
+// infoflow_send 参数 Schema
+// ---------------------------------------------------------------------------
+
+const InfoflowSendSchema = Type.Object({
+  to: Type.String({
+    description:
+      '消息目标。格式："用户名"（uuapName / 邮箱前缀）发私聊，"group:群ID" 发群消息（例如 "group:12600364"）。',
+  }),
+  message: Type.String({
+    description: "消息正文，支持 Markdown 格式。",
+  }),
+  atAll: Type.Optional(
+    Type.Boolean({
+      description: "群消息中是否 @全体成员，仅对群目标有效。",
+    }),
+  ),
+  mentionUserIds: Type.Optional(
+    Type.String({
+      description:
+        '需要 @ 的成员列表，逗号分隔的 uuapName（例如 "zhangsan,lisi"）。仅对群目标有效，atAll 为 true 时忽略。',
+    }),
+  ),
+  accountId: Type.Optional(
+    Type.String({
+      description: "多账号模式下指定账号 ID，不填则使用默认账号。",
+    }),
+  ),
+});
+
+type InfoflowSendParams = Static<typeof InfoflowSendSchema>;
+
+// ---------------------------------------------------------------------------
+// infoflow_recall 参数 Schema
+// ---------------------------------------------------------------------------
+
+const InfoflowRecallSchema = Type.Object({
+  to: Type.String({
+    description:
+      '要撤回消息的目标，格式与 infoflow_send 相同："用户名" 表示私聊，"group:群ID" 表示群聊。',
+  }),
+  count: Type.Optional(
+    Type.Number({
+      description: "撤回最近发送的 N 条消息（默认为 1）。",
+    }),
+  ),
+  messageId: Type.Optional(
+    Type.String({
+      description:
+        "按消息 ID 撤回指定消息。提供此参数时忽略 count。群消息所需的 msgseqid 会自动从消息记录中查找。",
+    }),
+  ),
+  accountId: Type.Optional(
+    Type.String({
+      description: "多账号模式下指定账号 ID，不填则使用默认账号。",
+    }),
+  ),
+});
+
+type InfoflowRecallParams = Static<typeof InfoflowRecallSchema>;
+
+// ---------------------------------------------------------------------------
+// 注册函数
+// ---------------------------------------------------------------------------
+
+/**
+ * 向 OpenClaw 插件 API 注册 infoflow_send 和 infoflow_recall 工具。
+ * 在插件的 register() 函数中调用。
+ */
+export function registerInfoflowTools(api: OpenClawPluginApi): void {
+  if (!api.config) {
+    api.logger.debug?.("infoflow_tools: No config available, skipping tool registration");
+    return;
+  }
+
+  // ---- infoflow_send：主动发消息 ----
+  api.registerTool(
+    {
+      name: "infoflow_send",
+      description:
+        "向如流（Infoflow）的用户或群发送消息。支持纯文本和 Markdown 格式。" +
+        "群消息可以 @指定成员 或 @全体成员。" +
+        "当需要主动发送通知、提醒或消息时使用此工具。",
+      parameters: InfoflowSendSchema,
+      async execute(_toolCallId, rawParams) {
+        const params = rawParams as InfoflowSendParams;
+        const { to: rawTo, message, atAll, mentionUserIds, accountId } = params;
+
+        // 标准化目标格式（去掉可能多余的前缀）
+        const to = normalizeInfoflowTarget(rawTo) ?? rawTo;
+        const isGroup = /^group:\d+$/i.test(to);
+
+        logVerbose(`[infoflow_send] to=${to}, isGroup=${isGroup}`);
+
+        const contents: Array<{ type: string; content: string }> = [];
+
+        // 群消息：先拼 @mention 块，再拼正文
+        if (isGroup) {
+          if (atAll) {
+            contents.push({ type: "at", content: "all" });
+          } else if (mentionUserIds) {
+            const ids = mentionUserIds
+              .split(",")
+              .map((s) => s.trim())
+              .filter(Boolean);
+            if (ids.length > 0) {
+              contents.push({ type: "at", content: ids.join(",") });
+            }
+          }
+        }
+
+        if (message.trim()) {
+          contents.push({ type: "markdown", content: message });
+        }
+
+        if (contents.length === 0) {
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "message is empty" }) }],
+            details: { ok: false, error: "message is empty" },
+          };
+        }
+
+        const result = await sendInfoflowMessage({
+          cfg: api.config!,
+          to,
+          contents,
+          accountId: accountId ?? undefined,
+        });
+
+        const payload = {
+          ok: result.ok,
+          channel: "infoflow",
+          to,
+          ...(result.messageId ? { messageId: result.messageId } : {}),
+          ...(result.error ? { error: result.error } : {}),
+        };
+
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(payload) }],
+          details: payload,
+        };
+      },
+    },
+    { name: "infoflow_send" },
+  );
+
+  // ---- infoflow_recall：撤回消息 ----
+  api.registerTool(
+    {
+      name: "infoflow_recall",
+      description:
+        "撤回机器人在如流（Infoflow）发送的消息。" +
+        "可按消息 ID 撤回指定消息，也可按数量撤回最近 N 条（默认 1 条）。" +
+        "当用户要求撤回、取消或删除刚发的如流消息时使用此工具。",
+      parameters: InfoflowRecallSchema,
+      async execute(_toolCallId, rawParams) {
+        const params = rawParams as InfoflowRecallParams;
+        const { to: rawTo, count = 1, messageId, accountId } = params;
+
+        const to = normalizeInfoflowTarget(rawTo) ?? rawTo;
+        const target = to.replace(/^infoflow:/i, "");
+
+        // 校验账号配置
+        const account = resolveInfoflowAccount({ cfg: api.config!, accountId: accountId ?? undefined });
+        if (!account.config.appKey || !account.config.appSecret) {
+          const err = { ok: false, error: "Infoflow appKey/appSecret not configured." };
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(err) }],
+            details: err,
+          };
+        }
+
+        const groupMatch = target.match(/^group:(\d+)/i);
+        // 统一返回格式的辅助函数
+        const json = (payload: unknown) => ({
+          content: [{ type: "text" as const, text: JSON.stringify(payload) }],
+          details: payload,
+        });
+
+        // ── 群消息撤回 ──
+        if (groupMatch) {
+          const groupId = Number(groupMatch[1]);
+
+          // 模式 A：按 messageId 撤回单条
+          if (messageId) {
+            // 群消息撤回需要同时提供 messageid + msgseqid，从本地消息记录中查找 msgseqid
+            const stored = querySentMessages(account.accountId, { target: `group:${groupId}`, count: 1 })
+              .find((r) => r.messageid === messageId);
+            const msgseqid = stored?.msgseqid ?? "";
+            if (!msgseqid) {
+              return json({ ok: false, error: "msgseqid not found for this messageId. It may have already been recalled or not found in the message store." });
+            }
+            const result = await recallInfoflowGroupMessage({ account, groupId, messageid: messageId, msgseqid });
+            if (result.ok) {
+              try { removeRecalledMessages(account.accountId, [messageId]); } catch { /* ignore */ }
+            }
+            return json({ ok: result.ok, to, ...(result.error ? { error: result.error } : {}) });
+          }
+
+          // 模式 B：按 count 批量撤回最近 N 条
+          const records = querySentMessages(account.accountId, { target: `group:${groupId}`, count })
+            .filter((r) => r.msgseqid); // 只撤回有 msgseqid 的记录
+
+          if (records.length === 0) {
+            return json({ ok: true, to, recalled: 0, message: "No recallable messages found." });
+          }
+
+          let succeeded = 0, failed = 0;
+          const recalledIds: string[] = [];
+          for (const r of records) {
+            const res = await recallInfoflowGroupMessage({ account, groupId, messageid: r.messageid, msgseqid: r.msgseqid });
+            if (res.ok) { succeeded++; recalledIds.push(r.messageid); } else { failed++; }
+          }
+          if (recalledIds.length > 0) {
+            try { removeRecalledMessages(account.accountId, recalledIds); } catch { /* ignore */ }
+          }
+          return json({ ok: failed === 0, to, recalled: succeeded, failed, total: records.length });
+        }
+
+        // ── 私聊消息撤回 ──
+        // 私聊撤回需要 appAgentId（企业后台的应用 ID）
+        const appAgentId = account.config.appAgentId;
+        if (!appAgentId) {
+          return json({ ok: false, error: "Private message recall requires appAgentId configuration." });
+        }
+
+        // 模式 A：按 messageId（即 msgkey）撤回单条
+        if (messageId) {
+          const result = await recallInfoflowPrivateMessage({ account, msgkey: messageId, appAgentId });
+          if (result.ok) {
+            try { removeRecalledMessages(account.accountId, [messageId]); } catch { /* ignore */ }
+          }
+          return json({ ok: result.ok, to, ...(result.error ? { error: result.error } : {}) });
+        }
+
+        // 模式 B：批量撤回最近 N 条
+        const records = querySentMessages(account.accountId, { target, count }).filter((r) => r.messageid);
+        if (records.length === 0) {
+          return json({ ok: true, to, recalled: 0, message: "No recallable messages found." });
+        }
+
+        let succeeded = 0, failed = 0;
+        const recalledIds: string[] = [];
+        for (const r of records) {
+          const res = await recallInfoflowPrivateMessage({ account, msgkey: r.messageid, appAgentId });
+          if (res.ok) { succeeded++; recalledIds.push(r.messageid); } else { failed++; }
+        }
+        if (recalledIds.length > 0) {
+          try { removeRecalledMessages(account.accountId, recalledIds); } catch { /* ignore */ }
+        }
+        return json({ ok: failed === 0, to, recalled: succeeded, failed, total: records.length });
+      },
+    },
+    { name: "infoflow_recall" },
+  );
+
+  api.logger.info?.("infoflow_tools: Registered infoflow_send and infoflow_recall tools");
+}

package/src/types.ts

@@ -0,0 +1,277 @@
+/**
+ * Infoflow channel type definitions.
+ */
+
+// ---------------------------------------------------------------------------
+// Policy types
+// ---------------------------------------------------------------------------
+
+export type InfoflowDmPolicy = "open" | "pairing" | "allowlist";
+export type InfoflowGroupPolicy = "open" | "allowlist" | "disabled";
+export type InfoflowChatType = "direct" | "group";
+export type InfoflowConnectionMode = "webhook" | "websocket";
+
+/** Reply mode controlling bot behavior per group */
+export type InfoflowReplyMode =
+  | "ignore"
+  | "record"
+  | "mention-only"
+  | "mention-and-watch"
+  | "proactive";
+
+/** Per-group configuration overrides */
+export type InfoflowGroupConfig = {
+  replyMode?: InfoflowReplyMode;
+  systemPrompt?: string;
+  /** Enable follow-up replies after bot responds (default: true) */
+  followUp?: boolean;
+  /** Follow-up window in seconds after last bot reply (default: 300) */
+  followUpWindow?: number;
+  /** Names to watch for @mentions */
+  watchMentions?: string[];
+  /** Regex pattern to watch for in message content */
+  watchRegex?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Inbound body item (for @mention detection in received messages)
+// ---------------------------------------------------------------------------
+
+/** Inbound body item from group messages (for @mention detection) */
+export type InfoflowInboundBodyItem = {
+  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 IDs extracted from inbound group AT items (excluding the bot itself) */
+export type InfoflowMentionIds = {
+  /** Human user userid list */
+  userIds: string[];
+  /** Robot robotid list (numbers, corresponding to outbound atagentids) */
+  agentIds: number[];
+};
+
+// ---------------------------------------------------------------------------
+// AT mention types
+// ---------------------------------------------------------------------------
+
+/** AT mention options for @mentioning members in group messages */
+export type InfoflowAtOptions = {
+  /** @all members; when true, atUserIds is ignored */
+  atAll?: boolean;
+  /** List of user IDs (uuapName) to @mention */
+  atUserIds?: string[];
+};
+
+/** Group message body item type */
+export type InfoflowGroupMessageBodyItem =
+  | { type: "TEXT"; content: string }
+  | { type: "MD"; content: string }
+  | { type: "AT"; atall?: boolean; atuserids: string[]; atagentids?: number[] }
+  | { type: "LINK"; href: string }
+  | { type: "IMAGE"; content: string };
+
+/** Content item for sendInfoflowMessage */
+export type InfoflowMessageContentItem = {
+  type: "text" | "markdown" | "at" | "at-agent" | "link" | "image";
+  content: string;
+};
+
+/** Outbound reply/quote context for group messages */
+export type InfoflowOutboundReply = {
+  /** Message ID of the message being replied to (string to preserve large integer precision) */
+  messageid: string;
+  /** Preview text of the quoted message */
+  preview?: string;
+  /** "1" = reply (default), "2" = quote */
+  replytype?: "1" | "2";
+  /** User IMID (optional, if not provided, shows robot name) */
+  imid?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Account configuration
+// ---------------------------------------------------------------------------
+
+export type InfoflowAccountConfig = {
+  enabled?: boolean;
+  name?: string;
+  apiHost?: string;
+  checkToken?: string;
+  encodingAESKey?: string;
+  appKey?: string;
+  appSecret?: string;
+  /** 连接方式：webhook（默认）或 websocket */
+  connectionMode?: InfoflowConnectionMode;
+  /** WebSocket Gateway 域名（仅 websocket 模式使用） */
+  wsGateway?: string;
+  dmPolicy?: InfoflowDmPolicy;
+  allowFrom?: string[];
+  groupPolicy?: InfoflowGroupPolicy;
+  groupAllowFrom?: string[];
+  requireMention?: boolean;
+  /** Robot name for matching @mentions in group messages */
+  robotName?: string;
+  /** Names to watch for @mentions; when someone @mentions a person in this list,
+   *  the bot analyzes the message and replies only if confident. */
+  watchMentions?: string[];
+  /** Regex pattern to watch for in message content; triggers bot activation when matched */
+  watchRegex?: string;
+  /** Reply mode controlling bot engagement level in groups */
+  replyMode?: InfoflowReplyMode;
+  /** Enable follow-up replies after bot responds to a mention (default: true) */
+  followUp?: boolean;
+  /** Follow-up window in seconds after last bot reply (default: 300) */
+  followUpWindow?: number;
+  /** 如流企业后台的应用ID（私聊消息撤回依赖此字段） */
+  appAgentId?: number;
+  /** Per-group configuration overrides, keyed by group ID */
+  groups?: Record<string, InfoflowGroupConfig>;
+  accounts?: Record<string, InfoflowAccountConfig>;
+  defaultAccount?: string;
+  /**
+   * Send a "processing" hint message immediately after receiving a message,
+   * before LLM starts responding. Helps users know the bot is working.
+   * Default: true
+   */
+  processingHint?: boolean;
+  /**
+   * Delay in seconds before sending the "processing" hint message.
+   * If LLM responds within this time, the hint is suppressed.
+   * Default: 5 (seconds). Set to 0 to send immediately.
+   */
+  processingHintDelay?: number;
+  /**
+   * Message format for outbound private (DM) messages: "text" or "markdown".
+   * Default: "text"
+   */
+  dmMessageFormat?: "text" | "markdown";
+  /**
+   * Message format for outbound group messages: "text" or "markdown".
+   * Note: "markdown" does not support reply-to (quote) context — the bot
+   * will still reply but without quoting the user's message.
+   * Default: "text"
+   */
+  groupMessageFormat?: "text" | "markdown";
+};
+
+export type ResolvedInfoflowAccount = {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  configured: boolean;
+  config: {
+    enabled?: boolean;
+    name?: string;
+    apiHost: string;
+    checkToken: string;
+    encodingAESKey: string;
+    appKey: string;
+    appSecret: string;
+    /** 连接方式：webhook（默认）或 websocket */
+    connectionMode?: InfoflowConnectionMode;
+    /** WebSocket Gateway 域名（仅 websocket 模式使用） */
+    wsGateway?: string;
+    dmPolicy?: InfoflowDmPolicy;
+    allowFrom?: string[];
+    groupPolicy?: InfoflowGroupPolicy;
+    groupAllowFrom?: string[];
+    requireMention?: boolean;
+    /** Robot name for matching @mentions in group messages */
+    robotName?: string;
+    /** Names to watch for @mentions; when someone @mentions a person in this list,
+     *  the bot analyzes the message and replies only if confident. */
+    watchMentions?: string[];
+    /** Regex pattern to watch for in message content; triggers bot activation when matched */
+    watchRegex?: string;
+    /** Reply mode controlling bot engagement level in groups */
+    replyMode?: InfoflowReplyMode;
+    /** Enable follow-up replies after bot responds to a mention (default: true) */
+    followUp?: boolean;
+    /** Follow-up window in seconds after last bot reply (default: 300) */
+    followUpWindow?: number;
+    /** 如流企业后台的应用ID（私聊消息撤回依赖此字段） */
+    appAgentId?: number;
+    /** Per-group configuration overrides, keyed by group ID */
+    groups?: Record<string, InfoflowGroupConfig>;
+    /**
+     * Message format for outbound private (DM) messages: "text" or "markdown".
+     * Default: "text"
+     */
+    dmMessageFormat?: "text" | "markdown";
+    /**
+     * Message format for outbound group messages: "text" or "markdown".
+     * Note: "markdown" does not support reply-to (quote) context.
+     * Default: "text"
+     */
+    groupMessageFormat?: "text" | "markdown";
+    dmPolicy?: string;
+    allowFrom?: string[];
+    groupPolicy?: string;
+    groupAllowFrom?: string[];
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Message types
+// ---------------------------------------------------------------------------
+
+export type InfoflowMessageEvent = {
+  fromuser: string;
+  mes: string;
+  chatType: InfoflowChatType;
+  groupId?: number;
+  senderName?: string;
+  /** Whether the bot was @mentioned in the message */
+  wasMentioned?: boolean;
+  /** Original message ID from Infoflow */
+  messageId?: string;
+  /** Unix millisecond timestamp of the message */
+  timestamp?: number;
+  /** Raw message text preserving @mentions (for RawBody) */
+  rawMes?: string;
+  /** Raw body items from group message (for watch-mention detection) */
+  bodyItems?: InfoflowInboundBodyItem[];
+  /** Non-bot mention IDs extracted from AT items in group messages (excluding bot itself) */
+  mentionIds?: InfoflowMentionIds;
+  /** Reply/quote context extracted from replyData body items (supports multiple quotes) */
+  replyContext?: string[];
+  /** Image download URLs extracted from IMAGE body items (group) or PicUrl (private) */
+  imageUrls?: string[];
+  /** Sender's IMID (numeric user ID) for reply context */
+  senderImid?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Handler parameter types
+// ---------------------------------------------------------------------------
+
+export type HandleInfoflowMessageParams = {
+  cfg: import("openclaw/plugin-sdk").OpenClawConfig;
+  event: InfoflowMessageEvent;
+  accountId: string;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+};
+
+export type HandlePrivateChatParams = {
+  cfg: import("openclaw/plugin-sdk").OpenClawConfig;
+  msgData: Record<string, unknown>;
+  accountId: string;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+};
+
+export type HandleGroupChatParams = {
+  cfg: import("openclaw/plugin-sdk").OpenClawConfig;
+  msgData: Record<string, unknown>;
+  accountId: string;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+};