@larksuite/openclaw-lark 2026.3.9

package/src/card/builder.js

@@ -0,0 +1,381 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Interactive card building for Feishu/Lark.
+ *
+ * Provides utilities to construct Feishu Interactive Message Cards for
+ * different agent response states (thinking, streaming, complete, confirm).
+ */
+import { optimizeMarkdownStyle } from './markdown-style';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Element ID used for the streaming text area in cards. The CardKit
+ * `cardElement.content()` API targets this element for typewriter-effect
+ * streaming updates.
+ */
+export const STREAMING_ELEMENT_ID = 'streaming_content';
+export const REASONING_ELEMENT_ID = 'reasoning_content';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+// ---- Reasoning text utilities ----
+// Mirrors the logic in the framework's `splitTelegramReasoningText` and
+// related helpers from `plugin-sdk/telegram/reasoning-lane-coordinator`.
+// Those are not exported from the public plugin-sdk entry, so we replicate
+// the same detection/splitting logic here.
+const REASONING_PREFIX = 'Reasoning:\n';
+/**
+ * Split a payload text into optional `reasoningText` and `answerText`.
+ *
+ * Handles two formats produced by the framework:
+ * 1. "Reasoning:\n_italic line_\n…" prefix (from `formatReasoningMessage`)
+ * 2. `<think>…</think>` / `<thinking>…</thinking>` XML tags
+ *
+ * Equivalent to the framework's `splitTelegramReasoningText()`.
+ */
+export function splitReasoningText(text) {
+    if (typeof text !== 'string' || !text.trim())
+        return {};
+    const trimmed = text.trim();
+    // Case 1: "Reasoning:\n..." prefix — the entire payload is reasoning
+    if (trimmed.startsWith(REASONING_PREFIX) && trimmed.length > REASONING_PREFIX.length) {
+        return { reasoningText: cleanReasoningPrefix(trimmed) };
+    }
+    // Case 2: XML thinking tags — extract content and strip from answer
+    const taggedReasoning = extractThinkingContent(text);
+    const strippedAnswer = stripReasoningTags(text);
+    if (!taggedReasoning && strippedAnswer === text) {
+        return { answerText: text };
+    }
+    return {
+        reasoningText: taggedReasoning || undefined,
+        answerText: strippedAnswer || undefined,
+    };
+}
+/**
+ * Extract content from `<think>`, `<thinking>`, `<thought>` blocks.
+ * Handles both closed and unclosed (streaming) tags.
+ */
+function extractThinkingContent(text) {
+    if (!text)
+        return '';
+    const scanRe = /<\s*(\/?)\s*(?:think(?:ing)?|thought|antthinking)\s*>/gi;
+    let result = '';
+    let lastIndex = 0;
+    let inThinking = false;
+    for (const match of text.matchAll(scanRe)) {
+        const idx = match.index ?? 0;
+        if (inThinking) {
+            result += text.slice(lastIndex, idx);
+        }
+        inThinking = match[1] !== '/';
+        lastIndex = idx + match[0].length;
+    }
+    // Handle unclosed tag (still streaming)
+    if (inThinking) {
+        result += text.slice(lastIndex);
+    }
+    return result.trim();
+}
+/**
+ * Strip reasoning blocks — both XML tags with their content and any
+ * "Reasoning:\n" prefixed content.
+ */
+export function stripReasoningTags(text) {
+    // Strip complete XML blocks
+    let result = text.replace(/<\s*(?:think(?:ing)?|thought|antthinking)\s*>[\s\S]*?<\s*\/\s*(?:think(?:ing)?|thought|antthinking)\s*>/gi, '');
+    // Strip unclosed tag at end (streaming)
+    result = result.replace(/<\s*(?:think(?:ing)?|thought|antthinking)\s*>[\s\S]*$/gi, '');
+    // Strip orphaned closing tags
+    result = result.replace(/<\s*\/\s*(?:think(?:ing)?|thought|antthinking)\s*>/gi, '');
+    return result.trim();
+}
+/**
+ * Clean a "Reasoning:\n_italic_" formatted message back to plain text.
+ * Strips the prefix and per-line italic markdown wrappers.
+ */
+function cleanReasoningPrefix(text) {
+    let cleaned = text.replace(/^Reasoning:\s*/i, '');
+    cleaned = cleaned
+        .split('\n')
+        .map((line) => line.replace(/^_(.+)_$/, '$1'))
+        .join('\n');
+    return cleaned.trim();
+}
+/**
+ * Format reasoning duration into a human-readable string.
+ * e.g. "Thought for 3.2s" or "Thought for 1m 15s"
+ */
+export function formatReasoningDuration(ms) {
+    return `Thought for ${formatElapsed(ms)}`;
+}
+/**
+ * Format milliseconds into a human-readable duration string.
+ */
+export function formatElapsed(ms) {
+    const seconds = ms / 1000;
+    return seconds < 60 ? `${seconds.toFixed(1)}s` : `${Math.floor(seconds / 60)}m ${Math.round(seconds % 60)}s`;
+}
+/**
+ * Build footer meta-info: hr separator + notation-sized text.
+ * Error text is rendered in red; normal text uses default grey (notation).
+ */
+function buildFooter(text, isError) {
+    const content = isError ? `<font color='red'>${text}</font>` : text;
+    return [{ tag: 'markdown', content, text_size: 'notation' }];
+}
+// ---------------------------------------------------------------------------
+// buildCardContent
+// ---------------------------------------------------------------------------
+/**
+ * Build a full Feishu Interactive Message Card JSON object for the
+ * given state.
+ */
+export function buildCardContent(state, data = {}) {
+    switch (state) {
+        case 'thinking':
+            return buildThinkingCard();
+        case 'streaming':
+            return buildStreamingCard(data.text ?? '', data.toolCalls ?? [], data.reasoningText);
+        case 'complete':
+            return buildCompleteCard({
+                text: data.text ?? '',
+                toolCalls: data.toolCalls ?? [],
+                elapsedMs: data.elapsedMs,
+                isError: data.isError,
+                reasoningText: data.reasoningText,
+                reasoningElapsedMs: data.reasoningElapsedMs,
+                isAborted: data.isAborted,
+                footer: data.footer,
+            });
+        case 'confirm':
+            return buildConfirmCard(data.confirmData);
+        default:
+            throw new Error(`Unknown card state: ${state}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Private card builders
+// ---------------------------------------------------------------------------
+function buildThinkingCard() {
+    return {
+        config: { wide_screen_mode: true, update_multi: true },
+        elements: [
+            {
+                tag: 'markdown',
+                content: '思考中...',
+            },
+        ],
+    };
+}
+function buildStreamingCard(partialText, toolCalls, reasoningText) {
+    const elements = [];
+    if (!partialText && reasoningText) {
+        // Reasoning phase: show reasoning content in notation style
+        elements.push({
+            tag: 'markdown',
+            content: `💭 **Thinking...**\n\n${reasoningText}`,
+            text_size: 'notation',
+        });
+    }
+    else if (partialText) {
+        // Answer phase: show answer content only
+        elements.push({
+            tag: 'markdown',
+            content: optimizeMarkdownStyle(partialText),
+        });
+    }
+    // Tool calls in progress
+    if (toolCalls.length > 0) {
+        const toolLines = toolCalls.map((tc) => {
+            const statusIcon = tc.status === 'running' ? '\ud83d\udd04' : tc.status === 'complete' ? '\u2705' : '\u274c';
+            return `${statusIcon} ${tc.name} - ${tc.status}`;
+        });
+        elements.push({
+            tag: 'markdown',
+            content: toolLines.join('\n'),
+            text_size: 'notation',
+        });
+    }
+    return {
+        config: { wide_screen_mode: true, update_multi: true },
+        elements,
+    };
+}
+function buildCompleteCard(params) {
+    const { text, toolCalls, elapsedMs, isError, reasoningText, reasoningElapsedMs, isAborted, footer } = params;
+    const elements = [];
+    // Collapsible reasoning panel (before main content)
+    if (reasoningText) {
+        const durationLabel = reasoningElapsedMs ? formatReasoningDuration(reasoningElapsedMs) : 'Thought';
+        elements.push({
+            tag: 'collapsible_panel',
+            expanded: false,
+            header: {
+                title: {
+                    tag: 'markdown',
+                    content: `💭 ${durationLabel}`,
+                },
+                vertical_align: 'center',
+                icon: {
+                    tag: 'standard_icon',
+                    token: 'down-small-ccm_outlined',
+                    size: '16px 16px',
+                },
+                icon_position: 'follow_text',
+                icon_expanded_angle: -180,
+            },
+            border: { color: 'grey', corner_radius: '5px' },
+            vertical_spacing: '8px',
+            padding: '8px 8px 8px 8px',
+            elements: [
+                {
+                    tag: 'markdown',
+                    content: reasoningText,
+                    text_size: 'notation',
+                },
+            ],
+        });
+    }
+    // Full text content
+    elements.push({
+        tag: 'markdown',
+        content: optimizeMarkdownStyle(text),
+    });
+    // Tool calls summary
+    if (toolCalls.length > 0) {
+        const toolSummaryLines = toolCalls.map((tc) => {
+            const statusIcon = tc.status === 'complete' ? '\u2705' : '\u274c';
+            return `${statusIcon} **${tc.name}** - ${tc.status}`;
+        });
+        elements.push({
+            tag: 'markdown',
+            content: toolSummaryLines.join('\n'),
+            text_size: 'notation',
+        });
+    }
+    // Footer meta-info: each metadata item is independently controlled via
+    // the `footer` config. Both status and elapsed default to hidden.
+    const parts = [];
+    if (footer?.status) {
+        if (isError) {
+            parts.push('出错');
+        }
+        else if (isAborted) {
+            parts.push('已停止');
+        }
+        else {
+            parts.push('已完成');
+        }
+    }
+    if (footer?.elapsed && elapsedMs != null) {
+        parts.push(`耗时 ${formatElapsed(elapsedMs)}`);
+    }
+    if (parts.length > 0) {
+        const footerText = parts.join(' · ');
+        elements.push(...buildFooter(footerText, isError));
+    }
+    // Use the answer text (not reasoning) as the feed preview summary.
+    // Strip markdown syntax so the preview reads as plain text.
+    const summaryText = text.replace(/[*_`#>\[\]()~]/g, '').trim();
+    const summary = summaryText ? { content: summaryText.slice(0, 120) } : undefined;
+    return {
+        config: { wide_screen_mode: true, update_multi: true, summary },
+        elements,
+    };
+}
+function buildConfirmCard(confirmData) {
+    const elements = [];
+    // Operation description
+    elements.push({
+        tag: 'div',
+        text: {
+            tag: 'lark_md',
+            content: confirmData.operationDescription,
+        },
+    });
+    // Preview (if available)
+    if (confirmData.preview) {
+        elements.push({ tag: 'hr' });
+        elements.push({
+            tag: 'div',
+            text: {
+                tag: 'lark_md',
+                content: `**Preview:**\n${confirmData.preview}`,
+            },
+        });
+    }
+    // Confirm / Reject / Preview buttons
+    elements.push({ tag: 'hr' });
+    elements.push({
+        tag: 'action',
+        actions: [
+            {
+                tag: 'button',
+                text: { tag: 'plain_text', content: 'Confirm' },
+                type: 'primary',
+                value: {
+                    action: 'confirm_write',
+                    operation_id: confirmData.pendingOperationId,
+                },
+            },
+            {
+                tag: 'button',
+                text: { tag: 'plain_text', content: 'Reject' },
+                type: 'danger',
+                value: {
+                    action: 'reject_write',
+                    operation_id: confirmData.pendingOperationId,
+                },
+            },
+            ...(confirmData.preview
+                ? []
+                : [
+                    {
+                        tag: 'button',
+                        text: {
+                            tag: 'plain_text',
+                            content: 'Preview',
+                        },
+                        type: 'default',
+                        value: {
+                            action: 'preview_write',
+                            operation_id: confirmData.pendingOperationId,
+                        },
+                    },
+                ]),
+        ],
+    });
+    return {
+        config: { wide_screen_mode: true, update_multi: true },
+        header: {
+            title: {
+                tag: 'plain_text',
+                content: '\ud83d\udd12 Confirmation Required',
+            },
+            template: 'orange',
+        },
+        elements,
+    };
+}
+// ---------------------------------------------------------------------------
+// toCardKit2
+// ---------------------------------------------------------------------------
+/**
+ * Convert an old-format FeishuCard to CardKit JSON 2.0 format.
+ * JSON 2.0 uses `body.elements` instead of top-level `elements`.
+ */
+export function toCardKit2(card) {
+    const result = {
+        schema: '2.0',
+        config: card.config,
+        body: { elements: card.elements },
+    };
+    if (card.header)
+        result.header = card.header;
+    return result;
+}
+//# sourceMappingURL=builder.js.map

package/src/card/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../../src/card/builder.ts"],"names":[],"mappings":"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"}

package/src/card/cardkit.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * CardKit streaming APIs for Feishu/Lark.
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+import type { FeishuSendResult } from '../messaging/types';
+/**
+ * Create a card entity via the CardKit API.
+ *
+ * Returns the card_id directly, bypassing the idConvert step.
+ * The card can then be sent via IM API and streamed via CardKit.
+ */
+export declare function createCardEntity(params: {
+    cfg: ClawdbotConfig;
+    card: Record<string, unknown>;
+    accountId?: string;
+}): Promise<string | null>;
+/**
+ * Stream text content to a specific card element using the CardKit API.
+ *
+ * The card automatically diffs the new content against the previous
+ * content and renders incremental changes with a typewriter animation.
+ *
+ * @param params.cardId    - CardKit card ID (from `convertMessageToCardId`).
+ * @param params.elementId - The element ID to update (e.g. `STREAMING_ELEMENT_ID`).
+ * @param params.content   - The full cumulative text (not a delta).
+ * @param params.sequence  - Monotonically increasing sequence number.
+ */
+export declare function streamCardContent(params: {
+    cfg: ClawdbotConfig;
+    cardId: string;
+    elementId: string;
+    content: string;
+    sequence: number;
+    accountId?: string;
+}): Promise<void>;
+/**
+ * Fully replace a card using the CardKit API.
+ *
+ * Used for the final "complete" state update (with action buttons, green
+ * header, etc.) after streaming finishes.
+ *
+ * @param params.cardId   - CardKit card ID.
+ * @param params.card     - The new card JSON content.
+ * @param params.sequence - Monotonically increasing sequence number.
+ */
+export declare function updateCardKitCard(params: {
+    cfg: ClawdbotConfig;
+    cardId: string;
+    card: Record<string, unknown>;
+    sequence: number;
+    accountId?: string;
+}): Promise<void>;
+export declare function updateCardKitCardForAuth(params: {
+    cfg: ClawdbotConfig;
+    cardId: string;
+    card: Record<string, unknown>;
+    sequence: number;
+    accountId?: string;
+}): Promise<void>;
+/**
+ * Send an interactive card message by referencing a CardKit card_id.
+ *
+ * The content format is: {"type":"card","data":{"card_id":"xxx"}}
+ * This links the IM message to the CardKit card entity, enabling
+ * streaming updates via cardElement.content().
+ */
+export declare function sendCardByCardId(params: {
+    cfg: ClawdbotConfig;
+    to: string;
+    cardId: string;
+    replyToMessageId?: string;
+    replyInThread?: boolean;
+    accountId?: string;
+}): Promise<FeishuSendResult>;
+/**
+ * Close (or open) the streaming mode on a CardKit card.
+ *
+ * Must be called after streaming is complete to restore normal card
+ * behaviour (forwarding, interaction callbacks, etc.).
+ */
+export declare function setCardStreamingMode(params: {
+    cfg: ClawdbotConfig;
+    cardId: string;
+    streamingMode: boolean;
+    sequence: number;
+    accountId?: string;
+}): Promise<void>;
+//# sourceMappingURL=cardkit.d.ts.map

package/src/card/cardkit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cardkit.d.ts","sourceRoot":"","sources":["../../../src/card/cardkit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAgD3D;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE;IAC7C,GAAG,EAAE,cAAc,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAkBzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE;IAC9C,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAehB;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE;IAC9C,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhB;AAED,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE;IAC7C,GAAG,EAAE,cAAc,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiD5B;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhB"}

package/src/card/cardkit.js

@@ -0,0 +1,182 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * CardKit streaming APIs for Feishu/Lark.
+ */
+import { LarkClient } from '../core/lark-client';
+import { larkLogger } from '../core/lark-logger';
+import { normalizeFeishuTarget, normalizeMessageId, resolveReceiveIdType } from '../core/targets';
+import { runWithMessageUnavailableGuard } from '../core/message-unavailable';
+const log = larkLogger('card/cardkit');
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * 记录 CardKit API 响应日志，检测错误码并抛出异常。
+ *
+ * 默认 fail-fast：body-level 非零 code 视为业务错误，立即抛出，
+ * 由调用方（streaming-card-controller 等）统一走 catch → guard 处理。
+ */
+function logCardKitResponse(params) {
+    const { resp, api, context } = params;
+    const { code, msg } = resp;
+    log.info(`cardkit ${api} response`, { code, msg, context });
+    if (code && code !== 0) {
+        log.warn(`cardkit ${api} FAILED`, { code, msg, context, fullResponse: resp });
+        throw new Error(`cardkit ${api} FAILED: code=${code}, msg=${msg ?? ''}, ${context}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// CardKit streaming APIs
+// ---------------------------------------------------------------------------
+/**
+ * Create a card entity via the CardKit API.
+ *
+ * Returns the card_id directly, bypassing the idConvert step.
+ * The card can then be sent via IM API and streamed via CardKit.
+ */
+export async function createCardEntity(params) {
+    const { cfg, card, accountId } = params;
+    const client = LarkClient.fromCfg(cfg, accountId).sdk;
+    // SDK 返回类型不完整，运行时包含 code/msg/data 字段
+    const response = (await client.cardkit.v1.card.create({
+        data: {
+            type: 'card_json',
+            data: JSON.stringify(card),
+        },
+    }));
+    // 兼容不同 SDK 包装层：优先 data.card_id，回退顶层 card_id
+    const cardId = (response.data?.card_id ?? response.card_id) ?? null;
+    logCardKitResponse({ resp: response, api: 'card.create', context: `cardId=${cardId}` });
+    return cardId;
+}
+/**
+ * Stream text content to a specific card element using the CardKit API.
+ *
+ * The card automatically diffs the new content against the previous
+ * content and renders incremental changes with a typewriter animation.
+ *
+ * @param params.cardId    - CardKit card ID (from `convertMessageToCardId`).
+ * @param params.elementId - The element ID to update (e.g. `STREAMING_ELEMENT_ID`).
+ * @param params.content   - The full cumulative text (not a delta).
+ * @param params.sequence  - Monotonically increasing sequence number.
+ */
+export async function streamCardContent(params) {
+    const { cfg, cardId, elementId, content, sequence, accountId } = params;
+    const client = LarkClient.fromCfg(cfg, accountId).sdk;
+    // SDK 返回类型不完整，运行时包含 code/msg 字段
+    const resp = (await client.cardkit.v1.cardElement.content({
+        data: { content, sequence },
+        path: { card_id: cardId, element_id: elementId },
+    }));
+    logCardKitResponse({
+        resp,
+        api: 'cardElement.content',
+        context: `seq=${sequence}, contentLen=${content.length}`,
+    });
+}
+/**
+ * Fully replace a card using the CardKit API.
+ *
+ * Used for the final "complete" state update (with action buttons, green
+ * header, etc.) after streaming finishes.
+ *
+ * @param params.cardId   - CardKit card ID.
+ * @param params.card     - The new card JSON content.
+ * @param params.sequence - Monotonically increasing sequence number.
+ */
+export async function updateCardKitCard(params) {
+    const { cfg, cardId, card, sequence, accountId } = params;
+    const client = LarkClient.fromCfg(cfg, accountId).sdk;
+    // SDK 返回类型不完整，运行时包含 code/msg 字段
+    const resp = (await client.cardkit.v1.card.update({
+        data: {
+            card: { type: 'card_json', data: JSON.stringify(card) },
+            sequence,
+        },
+        path: { card_id: cardId },
+    }));
+    logCardKitResponse({
+        resp,
+        api: 'card.update',
+        context: `seq=${sequence}, cardId=${cardId}`,
+    });
+}
+export async function updateCardKitCardForAuth(params) {
+    return updateCardKitCard(params);
+}
+/**
+ * Send an interactive card message by referencing a CardKit card_id.
+ *
+ * The content format is: {"type":"card","data":{"card_id":"xxx"}}
+ * This links the IM message to the CardKit card entity, enabling
+ * streaming updates via cardElement.content().
+ */
+export async function sendCardByCardId(params) {
+    const { cfg, to, cardId, replyToMessageId, replyInThread, accountId } = params;
+    const client = LarkClient.fromCfg(cfg, accountId).sdk;
+    const contentPayload = JSON.stringify({
+        type: 'card',
+        data: { card_id: cardId },
+    });
+    if (replyToMessageId) {
+        // 规范化 message_id，处理合成 ID（如 "om_xxx:auth-complete"）
+        const normalizedId = normalizeMessageId(replyToMessageId);
+        const response = await runWithMessageUnavailableGuard({
+            messageId: normalizedId,
+            operation: 'im.message.reply(interactive.cardkit)',
+            fn: () => client.im.message.reply({
+                path: { message_id: normalizedId },
+                data: { content: contentPayload, msg_type: 'interactive', reply_in_thread: replyInThread },
+            }),
+        });
+        return {
+            messageId: response?.data?.message_id ?? '',
+            chatId: response?.data?.chat_id ?? '',
+        };
+    }
+    const target = normalizeFeishuTarget(to);
+    if (!target) {
+        throw new Error(`[feishu-send] Invalid target: "${to}"`);
+    }
+    const receiveIdType = resolveReceiveIdType(target);
+    const response = await client.im.message.create({
+        // SDK 类型将 receive_id_type 限定为字面量联合，但运行时接受动态值
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        params: { receive_id_type: receiveIdType },
+        data: {
+            receive_id: target,
+            msg_type: 'interactive',
+            content: contentPayload,
+        },
+    });
+    return {
+        messageId: response?.data?.message_id ?? '',
+        chatId: response?.data?.chat_id ?? '',
+    };
+}
+/**
+ * Close (or open) the streaming mode on a CardKit card.
+ *
+ * Must be called after streaming is complete to restore normal card
+ * behaviour (forwarding, interaction callbacks, etc.).
+ */
+export async function setCardStreamingMode(params) {
+    const { cfg, cardId, streamingMode, sequence, accountId } = params;
+    const client = LarkClient.fromCfg(cfg, accountId).sdk;
+    // SDK 返回类型不完整，运行时包含 code/msg 字段
+    const resp = (await client.cardkit.v1.card.settings({
+        data: {
+            settings: JSON.stringify({ streaming_mode: streamingMode }),
+            sequence,
+        },
+        path: { card_id: cardId },
+    }));
+    logCardKitResponse({
+        resp,
+        api: 'card.settings',
+        context: `seq=${sequence}, streaming_mode=${streamingMode}`,
+    });
+}
+//# sourceMappingURL=cardkit.js.map