@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/messaging/inbound/enrich.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Context enrichment for inbound Feishu messages.
+ *
+ * Enrichment phases:
+ *
+ * - **resolveSenderInfo** (lightweight, before gate) — resolves sender
+ *   display name and tracks permission errors.
+ * - **prefetchUserNames** (after gate, before content resolution) — batch
+ *   pre-warm the account-scoped user-name cache for the sender and all
+ *   non-bot mentions so that downstream merge_forward expansion and
+ *   quoted-message formatting can read names synchronously.
+ * - **resolveMedia** (after gate) — downloads binary media attachments
+ *   using ResourceDescriptors from the converter phase.
+ * - **resolveQuotedContent** (after gate) — fetches the replied-to
+ *   message text for context.
+ *
+ * Note: merge_forward expansion for the primary message is now handled
+ * at parse time in {@link parseMessageEvent}. Quoted merge_forward
+ * messages are still expanded here via {@link resolveQuotedContent}.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSenderInfo = resolveSenderInfo;
+exports.prefetchUserNames = prefetchUserNames;
+exports.resolveMedia = resolveMedia;
+exports.substituteMediaPaths = substituteMediaPaths;
+exports.resolveQuotedContent = resolveQuotedContent;
+const fetch_1 = require("../outbound/fetch.js");
+const permission_1 = require("./permission.js");
+const user_name_cache_1 = require("./user-name-cache.js");
+const media_resolver_1 = require("./media-resolver.js");
+// ---------------------------------------------------------------------------
+// Phase 1: Sender info (lightweight, before gate)
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the sender display name and track permission errors.
+ *
+ * This must run before the gate check because per-group sender
+ * allowlists may match on senderName.
+ */
+async function resolveSenderInfo(params) {
+    const { account, log } = params;
+    let ctx = params.ctx;
+    // Bots and users have separate name-resolution endpoints. The contact API
+    // does not return bot info, so dispatch on senderIsBot. Both endpoints
+    // populate the same account-scoped cache (keyed by openId).
+    //
+    // Skip resolution for unknown sender_types (e.g. anonymous, missing) — the
+    // contact API would 4xx and the bot API would not match. This preserves the
+    // pre-bot-support behavior of only resolving names for `sender_type === 'user'`.
+    const senderType = ctx.rawSender?.sender_type;
+    if (!ctx.senderIsBot && senderType !== 'user') {
+        log(`sender_type is "${senderType ?? 'undefined'}", skipping name resolution`);
+        return { ctx };
+    }
+    const senderResult = ctx.senderIsBot
+        ? await (0, user_name_cache_1.resolveBotName)({ account, openId: ctx.senderId, log })
+        : await (0, user_name_cache_1.resolveUserName)({ account, openId: ctx.senderId, log });
+    if (senderResult.name) {
+        ctx = { ...ctx, senderName: senderResult.name };
+        log(`sender resolved: ${senderResult.name}`);
+    }
+    else if (senderResult.permissionError) {
+        log(`sender resolve failed: permission error code=${senderResult.permissionError.code}`);
+    }
+    // Track permission errors (with cooldown)
+    let permissionError;
+    if (senderResult.permissionError) {
+        const appKey = account.appId ?? 'default';
+        const now = Date.now();
+        const lastNotified = permission_1.permissionErrorNotifiedAt.get(appKey) ?? 0;
+        if (now - lastNotified > permission_1.PERMISSION_ERROR_COOLDOWN_MS) {
+            permission_1.permissionErrorNotifiedAt.set(appKey, now);
+            permissionError = senderResult.permissionError;
+        }
+    }
+    return { ctx, permissionError };
+}
+// ---------------------------------------------------------------------------
+// Phase 1.5: Batch pre-warm user name cache (after gate)
+// ---------------------------------------------------------------------------
+/**
+ * Batch-prefetch user display names for the sender and all non-bot
+ * mentions. Mention names that are already known from the event payload
+ * are written into the cache for free.
+ */
+async function prefetchUserNames(params) {
+    const { ctx, account, log } = params;
+    if (!account.configured)
+        return;
+    const cache = (0, user_name_cache_1.getUserNameCache)(account.accountId);
+    // Seed cache with mention names already present in the event payload
+    for (const m of ctx.mentions) {
+        if (!m.isBot && m.openId && m.name) {
+            cache.set(m.openId, m.name);
+        }
+    }
+    // Collect all openIds we care about
+    const openIds = new Set();
+    if (ctx.senderId)
+        openIds.add(ctx.senderId);
+    for (const m of ctx.mentions) {
+        if (!m.isBot && m.openId)
+            openIds.add(m.openId);
+    }
+    // Batch-resolve any that are still missing
+    const toResolve = cache.filterMissing([...openIds]);
+    if (toResolve.length > 0) {
+        await (0, user_name_cache_1.batchResolveUserNames)({ account, openIds: toResolve, log });
+    }
+}
+/**
+ * Download and save binary media attachments (images, files, audio,
+ * video, stickers) from the inbound message.
+ *
+ * Uses ResourceDescriptors extracted by content converters during the
+ * parse phase — no re-parsing of rawMessage.content needed.
+ *
+ * Returns a payload object whose keys (`MediaPath`, `MediaType`, …)
+ * are spread directly into the agent envelope, plus the raw mediaList
+ * for content substitution.
+ */
+async function resolveMedia(params) {
+    const { ctx, accountScopedCfg, account, log } = params;
+    const accountFeishuCfg = account.config;
+    const mediaMaxBytes = (accountFeishuCfg?.mediaMaxMb ?? 30) * 1024 * 1024;
+    const mediaList = await (0, media_resolver_1.downloadResources)({
+        cfg: accountScopedCfg,
+        messageId: ctx.messageId,
+        resources: ctx.resources,
+        maxBytes: mediaMaxBytes,
+        log,
+        accountId: account.accountId,
+    });
+    if (mediaList.length > 0) {
+        log(`media resolved: ${mediaList.length} attachment(s)`);
+    }
+    return {
+        payload: (0, media_resolver_1.buildFeishuMediaPayload)(mediaList),
+        mediaList,
+    };
+}
+// ---------------------------------------------------------------------------
+// Media content substitution
+// ---------------------------------------------------------------------------
+/**
+ * Replace Feishu file-key references in message content with actual
+ * local file paths after download.
+ *
+ * This is critical for:
+ * - **Images / stickers**: The SDK's `detectAndLoadPromptImages` scans
+ *   the prompt text for local file paths with image extensions.
+ * - **Audio / video / files**: Gives the AI meaningful context about
+ *   what was received (the SDK reads these via `MediaPath` directly,
+ *   but the text body should still reflect the actual attachments).
+ */
+function substituteMediaPaths(content, mediaList) {
+    let result = content;
+    for (const media of mediaList) {
+        const { fileKey, path, resourceType } = media;
+        switch (resourceType) {
+            case 'image':
+                // ![image](img_v3_xxx) → local path (SDK detects image extensions)
+                result = result.replace(`![image](${fileKey})`, path);
+                break;
+            case 'sticker':
+                // <sticker key="xxx"/> → local path (treated like image)
+                result = result.replace(`<sticker key="${fileKey}"/>`, path);
+                break;
+            case 'audio': {
+                // <audio key="xxx" .../> → [Audio: /path/to/audio.opus ...]
+                const audioRe = new RegExp(`<audio key="${escapeRegExp(fileKey)}"[^/]*/>`);
+                result = result.replace(audioRe, `[Audio: ${path}]`);
+                break;
+            }
+            case 'file': {
+                // <file key="xxx" .../> → [File: /path/to/doc.pdf]
+                const fileRe = new RegExp(`<file key="${escapeRegExp(fileKey)}"[^/]*/>`);
+                result = result.replace(fileRe, `[File: ${path}]`);
+                break;
+            }
+            case 'video': {
+                // <video key="xxx" .../> → [Video: /path/to/video.mp4]
+                const videoRe = new RegExp(`<video key="${escapeRegExp(fileKey)}"[^/]*/>`);
+                result = result.replace(videoRe, `[Video: ${path}]`);
+                break;
+            }
+        }
+    }
+    return result;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// ---------------------------------------------------------------------------
+// Phase 2b: Quoted / replied-to message (text context)
+// ---------------------------------------------------------------------------
+/**
+ * Fetch the text content of the message that the user replied to.
+ *
+ * If the quoted message is itself a merge_forward, its sub-messages are
+ * fetched and formatted as a single text block.
+ *
+ * Returns `"senderName: content"` when the sender name is available so
+ * the AI knows who originally wrote the quoted message.
+ */
+async function resolveQuotedContent(params) {
+    const { ctx, accountScopedCfg, account, log } = params;
+    if (!ctx.parentId)
+        return undefined;
+    try {
+        const quotedMsg = await (0, fetch_1.getMessageFeishu)({
+            cfg: accountScopedCfg,
+            messageId: ctx.parentId,
+            accountId: account.accountId,
+            expandForward: true,
+        });
+        if (!quotedMsg)
+            return undefined;
+        log(`feishu[${account.accountId}]: fetched quoted message: ${quotedMsg.content?.slice(0, 100)}`);
+        // Build quoted text with message_id prefix so AI can correlate
+        // file_key / image_key with the source message for resource download.
+        const prefix = `[message_id=${ctx.parentId}]`;
+        if (quotedMsg.senderName) {
+            return `${prefix} ${quotedMsg.senderName}: ${quotedMsg.content}`;
+        }
+        return `${prefix} ${quotedMsg.content}`;
+    }
+    catch (err) {
+        log(`feishu[${account.accountId}]: failed to fetch quoted message: ${String(err)}`);
+        return undefined;
+    }
+}

package/src/messaging/inbound/gate-effects.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Side-effect functions for the inbound message gate.
+ *
+ * Extracted from gate.ts to separate pure policy decisions from I/O
+ * operations (pairing request creation, message sending).
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+/**
+ * Create a pairing request and send a pairing reply message to the user.
+ *
+ * This is the side-effect portion of the DM pairing gate: the pure
+ * policy decision (whether to pair) is made in gate.ts, and this
+ * function executes the resulting I/O.
+ */
+export declare function sendPairingReply(params: {
+    senderId: string;
+    chatId: string;
+    accountId: string;
+    accountScopedCfg?: ClawdbotConfig;
+}): Promise<void>;

package/src/messaging/inbound/gate-effects.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Side-effect functions for the inbound message gate.
+ *
+ * Extracted from gate.ts to separate pure policy decisions from I/O
+ * operations (pairing request creation, message sending).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendPairingReply = sendPairingReply;
+const lark_client_1 = require("../../core/lark-client.js");
+const send_1 = require("../outbound/send.js");
+// ---------------------------------------------------------------------------
+// Pairing reply
+// ---------------------------------------------------------------------------
+/**
+ * Create a pairing request and send a pairing reply message to the user.
+ *
+ * This is the side-effect portion of the DM pairing gate: the pure
+ * policy decision (whether to pair) is made in gate.ts, and this
+ * function executes the resulting I/O.
+ */
+async function sendPairingReply(params) {
+    const { senderId, chatId, accountId, accountScopedCfg } = params;
+    const core = lark_client_1.LarkClient.runtime;
+    const { code } = await core.channel.pairing.upsertPairingRequest({
+        channel: 'feishu',
+        id: senderId,
+        accountId,
+    });
+    const pairingReply = core.channel.pairing.buildPairingReply({
+        channel: 'feishu',
+        idLine: senderId,
+        code,
+    });
+    if (accountScopedCfg) {
+        await (0, send_1.sendMessageFeishu)({
+            cfg: accountScopedCfg,
+            to: chatId,
+            text: pairingReply,
+            accountId,
+        });
+    }
+}

package/src/messaging/inbound/gate.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Policy gate for inbound Feishu messages.
+ *
+ * Determines whether a parsed message should be processed or rejected
+ * based on group/DM access policies, sender allowlists, and mention
+ * requirements.
+ *
+ * Group access follows the same two-layer model as Telegram:
+ *
+ *   Layer 1 – Which GROUPS are allowed (SDK `resolveGroupPolicy`):
+ *     - No `groups` configured + `groupPolicy: "open"` → any group passes
+ *     - `groupPolicy: "allowlist"` or `groups` configured → acts as allowlist
+ *       (explicit group IDs or `"*"` wildcard)
+ *     - `groupPolicy: "disabled"` → all groups blocked
+ *
+ *   Layer 2 – Which SENDERS are allowed within a group:
+ *     - Per-group `groupPolicy` overrides global for sender filtering
+ *     - `groupAllowFrom` (global) + per-group `allowFrom` are merged
+ *     - `"open"` → any sender; `"allowlist"` → check merged list;
+ *       `"disabled"` → block all senders
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+import type { HistoryEntry } from 'openclaw/plugin-sdk/reply-history';
+import type { MessageContext } from '../types';
+import type { FeishuConfig, FeishuGroupConfig, LarkAccount } from '../../core/types';
+/**
+ * Resolve the effective `respondToMentionAll` setting.
+ *
+ * Precedence: per-group > default ("*") group > global account config > false.
+ */
+export declare function resolveRespondToMentionAll(params: {
+    groupConfig?: {
+        respondToMentionAll?: boolean;
+    };
+    defaultConfig?: {
+        respondToMentionAll?: boolean;
+    };
+    accountFeishuCfg?: {
+        respondToMentionAll?: boolean;
+    };
+}): boolean;
+/**
+ * Resolve the effective allowBots setting.
+ *
+ * Precedence: per-group > default ("*") > account > 'mentions'.
+ *
+ * The `'mentions'` default lets bot-to-bot interaction work out of the box
+ * while still requiring an explicit @-mention in groups; DMs treat it as
+ * pass-through. Operators can opt into fully-open (`true`) or fully-closed
+ * (`false`) explicitly.
+ */
+export declare function resolveAllowBots(params: {
+    groupConfig?: FeishuGroupConfig;
+    defaultConfig?: FeishuGroupConfig;
+    accountFeishuCfg?: FeishuConfig;
+}): boolean | 'mentions';
+/**
+ * Read the pairing allowFrom store for the Feishu channel via the SDK runtime.
+ */
+declare function readAllowFromStore(accountId: string): Promise<string[]>;
+export interface GateResult {
+    allowed: boolean;
+    reason?: string;
+    /** When a group message is rejected due to missing bot mention, the
+     *  caller should record this entry into the chat history map. */
+    historyEntry?: HistoryEntry;
+}
+/**
+ * Read the pairing allowFrom store for the Feishu channel.
+ *
+ * Exported so that handler.ts can provide it as a closure to the SDK's
+ * `resolveSenderCommandAuthorization` helper.
+ */
+export { readAllowFromStore as readFeishuAllowFromStore };
+/**
+ * Check whether an inbound message passes all access-control gates.
+ *
+ * The DM gate is async because it may read from the pairing store
+ * and send pairing request messages.
+ */
+export declare function checkMessageGate(params: {
+    ctx: MessageContext;
+    accountFeishuCfg?: FeishuConfig;
+    account: LarkAccount;
+    /** account 级别的 ClawdbotConfig（channels.feishu 已替换为 per-account 合并后的配置） */
+    accountScopedCfg?: ClawdbotConfig;
+    log: (...args: unknown[]) => void;
+}): Promise<GateResult>;