@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/messaging/shared/message-lookup.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Message fetching for the Lark/Feishu channel plugin.
+ *
+ * Shared between inbound (reaction handler, enrich) and outbound modules.
+ * Extracted from `outbound/fetch.ts` to eliminate inbound→outbound
+ * dependency inversion.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMessageFeishu = getMessageFeishu;
+const content_converter_1 = require("../converters/content-converter.js");
+const lark_client_1 = require("../../core/lark-client.js");
+const lark_logger_1 = require("../../core/lark-logger.js");
+const log = (0, lark_logger_1.larkLogger)('shared/message-lookup');
+const user_name_cache_1 = require("../inbound/user-name-cache.js");
+const accounts_1 = require("../../core/accounts.js");
+// ---------------------------------------------------------------------------
+// getMessageFeishu
+// ---------------------------------------------------------------------------
+/**
+ * Retrieve a single message by its ID from the Feishu IM API.
+ *
+ * Returns a normalised {@link FeishuMessageInfo} object, or `null` if the
+ * message cannot be found or the API returns an error.
+ *
+ * @param params.cfg       - Plugin configuration with Feishu credentials.
+ * @param params.messageId - The message ID to fetch.
+ * @param params.accountId - Optional account identifier for multi-account setups.
+ */
+async function getMessageFeishu(params) {
+    const { cfg, messageId, accountId, expandForward } = params;
+    const larkClient = lark_client_1.LarkClient.fromCfg(cfg, accountId);
+    const sdk = larkClient.sdk;
+    try {
+        const requestOpts = {
+            method: 'GET',
+            url: `/open-apis/im/v1/messages/mget`,
+            params: {
+                message_ids: messageId,
+                user_id_type: 'open_id',
+                card_msg_content_type: 'raw_card_content',
+            },
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const response = await sdk.request(requestOpts);
+        const items = response?.data?.items;
+        if (!items || items.length === 0) {
+            log.info(`getMessageFeishu: no items returned for ${messageId}`);
+            return null;
+        }
+        const expandCtx = expandForward
+            ? {
+                cfg,
+                accountId,
+                fetchSubMessages: async (msgId) => {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const res = await larkClient.sdk.request({
+                        method: 'GET',
+                        url: `/open-apis/im/v1/messages/${msgId}`,
+                        params: { user_id_type: 'open_id', card_msg_content_type: 'raw_card_content' },
+                    });
+                    if (res?.code !== 0) {
+                        throw new Error(`API error: code=${res?.code} msg=${res?.msg}`);
+                    }
+                    return res?.data?.items ?? [];
+                },
+                batchResolveNames: (0, user_name_cache_1.createBatchResolveNames)((0, accounts_1.getLarkAccount)(cfg, accountId), (...args) => log.info(args.map(String).join(' '))),
+            }
+            : undefined;
+        return await parseMessageItem(items[0], messageId, expandCtx);
+    }
+    catch (error) {
+        log.error(`get message failed (${messageId}): ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Parse a single message item from the Feishu IM API response into a
+ * normalised {@link FeishuMessageInfo}.
+ *
+ * Content parsing is delegated to the shared converter system so that
+ * every message-type mapping is defined in exactly one place.
+ */
+async function parseMessageItem(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+msg, fallbackMessageId, expandCtx) {
+    const msgType = msg.msg_type ?? 'text';
+    const rawContent = msg.body?.content ?? '{}';
+    const messageId = msg.message_id ?? fallbackMessageId;
+    const acctId = expandCtx?.accountId;
+    const ctx = {
+        ...(0, content_converter_1.buildConvertContextFromItem)(msg, fallbackMessageId, acctId),
+        cfg: expandCtx?.cfg,
+        accountId: acctId,
+        fetchSubMessages: expandCtx?.fetchSubMessages,
+        batchResolveNames: expandCtx?.batchResolveNames,
+    };
+    const { content } = await (0, content_converter_1.convertMessageContent)(rawContent, msgType, ctx);
+    const senderId = msg.sender?.id ?? undefined;
+    const senderType = msg.sender?.sender_type ?? undefined;
+    const senderName = senderId && acctId ? (0, user_name_cache_1.getUserNameCache)(acctId).get(senderId) : undefined;
+    return {
+        messageId,
+        chatId: msg.chat_id ?? '',
+        chatType: msg.chat_type ?? undefined,
+        senderId,
+        senderName,
+        senderType,
+        content,
+        contentType: msgType,
+        createTime: msg.create_time ? parseInt(String(msg.create_time), 10) : undefined,
+        threadId: msg.thread_id || undefined,
+    };
+}

package/src/messaging/types.d.ts

@@ -0,0 +1,316 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Messaging type definitions for the Lark/Feishu channel plugin.
+ *
+ * Pure shape types for inbound message events, normalised message context,
+ * mention targets, and media metadata.
+ */
+export interface FeishuMessageEvent {
+    sender: {
+        sender_id: {
+            open_id?: string;
+            user_id?: string;
+            union_id?: string;
+        };
+        sender_type?: string;
+        tenant_key?: string;
+    };
+    message: {
+        message_id: string;
+        root_id?: string;
+        parent_id?: string;
+        create_time?: string;
+        update_time?: string;
+        chat_id: string;
+        thread_id?: string;
+        chat_type: 'p2p' | 'group';
+        message_type: string;
+        content: string;
+        mentions?: Array<{
+            key: string;
+            id: {
+                open_id?: string;
+                user_id?: string;
+                union_id?: string;
+            };
+            name: string;
+            tenant_key?: string;
+        }>;
+        user_agent?: string;
+    };
+}
+export interface FeishuReactionCreatedEvent {
+    message_id: string;
+    chat_id?: string;
+    chat_type?: 'p2p' | 'group' | 'private';
+    reaction_type?: {
+        emoji_type?: string;
+    };
+    operator_type?: string;
+    user_id?: {
+        open_id?: string;
+        user_id?: string;
+        union_id?: string;
+    };
+    action_time?: string;
+}
+/**
+ * Raw event shape for `drive.notice.comment_add_v1`.
+ *
+ * Fired when a user adds a comment or reply on a Drive document.
+ * The SDK flattens the v2 envelope header into the handler `data` object,
+ * so `app_id` is available directly on the event.
+ *
+ * **Real event structure** (SDK-flattened):
+ * ```json
+ * {
+ *   "app_id": "cli_xxx",
+ *   "file_token": "xxx",
+ *   "file_type": "docx",
+ *   "comment_id": "xxx",
+ *   "reply_id": "xxx",          // optional, present for replies
+ *   "notice_meta": {
+ *     "from_user_id": { "open_id": "ou_xxx", "user_id": "xxx", "union_id": "xxx" },
+ *     "timestamp": "1712000000000",
+ *     "is_mentioned": true
+ *   }
+ * }
+ * ```
+ *
+ * Some fields may also appear at top-level depending on SDK version,
+ * so the parser checks both locations.
+ */
+export interface FeishuDriveCommentEvent {
+    /** App ID from the event envelope header. */
+    app_id?: string;
+    /** File token of the document where the comment was added. */
+    file_token?: string;
+    /** File type: doc, docx, sheet, file, slides, etc. */
+    file_type?: string;
+    /** Comment ID of the root comment. */
+    comment_id?: string;
+    /** Reply ID (present when the event is a reply, not a root comment). */
+    reply_id?: string;
+    /**
+     * Metadata about the notice — primary location for user info and timestamp.
+     * Present in the real event structure; not always at top level.
+     */
+    notice_meta?: {
+        from_user_id?: {
+            open_id?: string;
+            user_id?: string;
+            union_id?: string;
+        };
+        file_token?: string;
+        file_type?: string;
+        timestamp?: string;
+        is_mentioned?: boolean;
+    };
+    /** Whether the bot was @-mentioned in this comment. */
+    is_mention?: boolean;
+    /** Fallback: user ID at top level (some SDK flattening styles). */
+    user_id?: {
+        open_id?: string;
+        user_id?: string;
+        union_id?: string;
+    };
+    /** Fallback: event timestamp at top level. */
+    action_time?: string;
+}
+export interface FeishuBotAddedEvent {
+    chat_id: string;
+    operator_id: {
+        open_id?: string;
+        user_id?: string;
+        union_id?: string;
+    };
+    external: boolean;
+    operator_tenant_key?: string;
+    name?: string;
+    i18n_names?: {
+        zh_cn?: string;
+        en_us?: string;
+        ja_jp?: string;
+    };
+}
+/**
+ * Raw event shape for `vc.bot.meeting_invited_v1`.
+ *
+ * Fired when a user invites the bot to join a meeting.
+ *
+ * Identity fields (for bot / inviter / host_user) are nested under an
+ * `id` object; individual id variants (open_id / user_id / union_id)
+ * may be null depending on the tenant configuration.
+ */
+export interface FeishuVcMeetingInvitedEvent {
+    app_id?: string;
+    event_id?: string;
+    meeting?: {
+        id?: string;
+        meeting_no?: string;
+        topic?: string;
+        host_user?: {
+            id?: {
+                open_id?: string | null;
+                user_id?: string | null;
+                union_id?: string | null;
+            };
+            user_name?: string;
+        };
+    };
+    bot?: {
+        id?: {
+            open_id?: string | null;
+            user_id?: string | null;
+            union_id?: string | null;
+        };
+        user_name?: string;
+    };
+    inviter?: {
+        id?: {
+            open_id?: string | null;
+            user_id?: string | null;
+            union_id?: string | null;
+        };
+        user_name?: string;
+    };
+    invite_time?: string;
+    /** Correlation id carried by the invite event; forward to the join tool when present. */
+    call_id?: string;
+}
+/**
+ * Internal synthetic event model for VC meeting-invited flows.
+ *
+ * This preserves the business semantics before the event is converted into a
+ * synthetic MessageContext for dispatchToAgent().
+ */
+export interface VcMeetingInvitedSyntheticEvent {
+    eventType: 'vc.bot.meeting_invited_v1';
+    source: 'feishu-vc-event';
+    eventId?: string;
+    meetingId?: string;
+    meetingNo: string;
+    topic?: string;
+    senderId: string;
+    senderOpenId?: string;
+    senderUserId?: string;
+    senderUnionId?: string;
+    senderName?: string;
+    inviteTime?: string;
+    /** Correlation id forwarded from the invite event; pass through to the join tool. */
+    callId?: string;
+}
+/** Metadata describing a media resource in a message (no binary data). */
+export interface ResourceDescriptor {
+    type: 'image' | 'file' | 'audio' | 'video' | 'sticker';
+    /** image_key or file_key from the raw message content. */
+    fileKey: string;
+    /** Original file name (file/video messages). */
+    fileName?: string;
+    /** Duration in milliseconds (audio/video messages). */
+    duration?: number;
+    /** Video cover image key. */
+    coverImageKey?: string;
+}
+/** Structured @mention information from a message. */
+export interface MentionInfo {
+    /** Placeholder key in raw content (e.g. "@_user_1"). */
+    key: string;
+    /** Feishu Open ID of the mentioned user. */
+    openId: string;
+    /** Display name. */
+    name: string;
+    /** True iff this mention targets the receiving bot itself (openId === botOpenId). */
+    isBot: boolean;
+}
+/** Raw message body, directly mapped from FeishuMessageEvent.message. */
+export interface RawMessage {
+    message_id: string;
+    root_id?: string;
+    parent_id?: string;
+    create_time?: string;
+    update_time?: string;
+    chat_id: string;
+    thread_id?: string;
+    chat_type: 'p2p' | 'group';
+    message_type: string;
+    content: string;
+    mentions?: Array<{
+        key: string;
+        id: {
+            open_id?: string;
+            user_id?: string;
+            union_id?: string;
+        };
+        name: string;
+        tenant_key?: string;
+    }>;
+    user_agent?: string;
+}
+/** Raw sender data, directly mapped from FeishuMessageEvent.sender. */
+export interface RawSender {
+    sender_id: {
+        open_id?: string;
+        user_id?: string;
+        union_id?: string;
+    };
+    sender_type?: string;
+    tenant_key?: string;
+}
+/** Normalised representation of an inbound Feishu message. */
+export interface MessageContext {
+    chatId: string;
+    messageId: string;
+    senderId: string;
+    senderName?: string;
+    chatType: 'p2p' | 'group';
+    content: string;
+    contentType: string;
+    /** Media resource descriptors extracted during parsing. */
+    resources: ResourceDescriptor[];
+    /** All @mentions in the message (including bot). */
+    mentions: MentionInfo[];
+    /** Whether an @all / @所有人 mention was detected in the message. */
+    mentionAll: boolean;
+    /**
+     * True when the event sender is a bot/app (sender_type === 'app').
+     *
+     * Set by parseMessageEvent. Optional because synthetic construction sites
+     * (comment / reaction / vc-invited handlers) omit it — absence is treated
+     * as `false` since those paths only originate from human actors today.
+     */
+    senderIsBot?: boolean;
+    rootId?: string;
+    parentId?: string;
+    threadId?: string;
+    createTime?: number;
+    rawMessage: RawMessage;
+    rawSender: RawSender;
+}
+/** @deprecated Use {@link MessageContext} instead. */
+export type FeishuMessageContext = MessageContext;
+/** Metadata about a media attachment received in or sent through Feishu. */
+export interface FeishuMediaInfo {
+    path: string;
+    contentType?: string;
+    placeholder: string;
+    /** Original Feishu file_key / image_key that was downloaded. */
+    fileKey: string;
+    /** Resource type from the original descriptor. */
+    resourceType: ResourceDescriptor['type'];
+}
+/** Result of sending a message via the Feishu API. */
+export interface FeishuSendResult {
+    messageId: string;
+    chatId: string;
+    /**
+     * Human-readable warning when the send succeeded but with degradation
+     * (e.g. media upload failed, fell back to a text link).
+     *
+     * Populated so upstream callers (and the AI) can detect that the
+     * delivery was not fully as intended and take corrective action.
+     */
+    warning?: string;
+}

package/src/messaging/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Messaging type definitions for the Lark/Feishu channel plugin.
+ *
+ * Pure shape types for inbound message events, normalised message context,
+ * mention targets, and media metadata.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/tools/ask-user-question.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * AskUserQuestion tool — AI agent 主动向用户提问并等待回答。
+ *
+ * 流程（非阻塞，遵循 auto-auth synthetic message 模式）：
+ * 1. AI 调用 AskUserQuestion 工具，传入问题和选项
+ * 2. 发送 form 交互式飞书卡片
+ * 3. 工具 execute() 立即返回 { status: 'pending' }
+ * 4. 用户填写表单并点击提交，form_value 一次性回传
+ * 5. handleAskUserAction 解析答案，注入 synthetic message
+ * 6. AI 在新一轮对话中收到用户答案
+ *
+ * 所有卡片统一使用 form 容器，交互组件在本地缓存值，
+ * 提交时通过 form_value 一次性回调，避免独立回调导致的 loading 闪烁。
+ *
+ * 注意：提交按钮必须设置 value 字段。飞书客户端会校验交互组件是否携带 value，
+ * 缺失时直接报 200340 错误，回调不会发送到服务端。虽然 form_submit 场景下
+ * form_value 是主要数据载体，但 value 作为按钮的合法性标记仍需存在。
+ */
+import type { ClawdbotConfig, OpenClawPluginApi } from 'openclaw/plugin-sdk';
+/**
+ * 处理 form 表单提交事件。
+ *
+ * 统一使用 form 后，所有值通过 form_value 一次性提交。
+ * 解析答案后注入 synthetic message，AI 在新一轮对话中收到答案。
+ *
+ * @returns 卡片回调响应，或 undefined 表示非本模块的 action
+ */
+export declare function handleAskUserAction(data: unknown, _cfg: ClawdbotConfig, accountId: string): unknown | undefined;
+export declare function registerAskUserQuestionTool(api: OpenClawPluginApi): void;