@colinlu50/openclaw-lark-stream 2026.3.17

package/src/card/cardkit.js

@@ -0,0 +1,181 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * CardKit streaming APIs for Lark/Feishu.
+ */
+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}`,
+    });
+}

package/src/card/flush-controller.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Generic throttled flush controller.
+ *
+ * A pure scheduling primitive that manages timer-based throttling,
+ * mutex-guarded flushing, and reflush-on-conflict. Contains no
+ * business logic — the actual flush work is provided via a callback.
+ */
+export declare class FlushController {
+    private readonly doFlush;
+    private flushInProgress;
+    private flushResolvers;
+    private needsReflush;
+    private pendingFlushTimer;
+    private lastUpdateTime;
+    private isCompleted;
+    constructor(doFlush: () => Promise<void>);
+    /** Mark the controller as completed — no more flushes after current one. */
+    complete(): void;
+    /** Cancel any pending deferred flush timer. */
+    cancelPendingFlush(): void;
+    /** Wait for any in-progress flush to finish. */
+    waitForFlush(): Promise<void>;
+    /**
+     * Execute a flush (mutex-guarded, with reflush on conflict).
+     *
+     * If a flush is already in progress, marks needsReflush so a
+     * follow-up flush fires immediately after the current one completes.
+     */
+    flush(): Promise<void>;
+    /**
+     * Throttled update entry point.
+     *
+     * @param throttleMs - Minimum interval between flushes (varies by
+     *   CardKit vs IM patch mode). Passed in by the caller so this
+     *   controller remains business-logic-free.
+     */
+    throttledUpdate(throttleMs: number): Promise<void>;
+    /** Overridable gate: subclasses / consumers can set via setCardMessageReady. */
+    private _cardMessageReady;
+    cardMessageReady(): boolean;
+    setCardMessageReady(ready: boolean): void;
+}

package/src/card/flush-controller.js

@@ -0,0 +1,134 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Generic throttled flush controller.
+ *
+ * A pure scheduling primitive that manages timer-based throttling,
+ * mutex-guarded flushing, and reflush-on-conflict. Contains no
+ * business logic — the actual flush work is provided via a callback.
+ */
+import { THROTTLE_CONSTANTS } from './reply-dispatcher-types';
+// ---------------------------------------------------------------------------
+// FlushController
+// ---------------------------------------------------------------------------
+export class FlushController {
+    doFlush;
+    flushInProgress = false;
+    flushResolvers = [];
+    needsReflush = false;
+    pendingFlushTimer = null;
+    lastUpdateTime = 0;
+    isCompleted = false;
+    constructor(doFlush) {
+        this.doFlush = doFlush;
+    }
+    /** Mark the controller as completed — no more flushes after current one. */
+    complete() {
+        this.isCompleted = true;
+    }
+    /** Cancel any pending deferred flush timer. */
+    cancelPendingFlush() {
+        if (this.pendingFlushTimer) {
+            clearTimeout(this.pendingFlushTimer);
+            this.pendingFlushTimer = null;
+        }
+    }
+    /** Wait for any in-progress flush to finish. */
+    waitForFlush() {
+        if (!this.flushInProgress)
+            return Promise.resolve();
+        return new Promise((resolve) => this.flushResolvers.push(resolve));
+    }
+    /**
+     * Execute a flush (mutex-guarded, with reflush on conflict).
+     *
+     * If a flush is already in progress, marks needsReflush so a
+     * follow-up flush fires immediately after the current one completes.
+     */
+    async flush() {
+        if (!this.cardMessageReady() || this.flushInProgress || this.isCompleted) {
+            if (this.flushInProgress && !this.isCompleted)
+                this.needsReflush = true;
+            return;
+        }
+        this.flushInProgress = true;
+        this.needsReflush = false;
+        // Update timestamp BEFORE the API call to prevent concurrent callers
+        // from also entering the flush (race condition fix).
+        this.lastUpdateTime = Date.now();
+        try {
+            await this.doFlush();
+            this.lastUpdateTime = Date.now();
+        }
+        finally {
+            this.flushInProgress = false;
+            const resolvers = this.flushResolvers;
+            this.flushResolvers = [];
+            for (const resolve of resolvers)
+                resolve();
+            // If events arrived while the API call was in flight,
+            // schedule an immediate follow-up flush.
+            if (this.needsReflush && !this.isCompleted && !this.pendingFlushTimer) {
+                this.needsReflush = false;
+                this.pendingFlushTimer = setTimeout(() => {
+                    this.pendingFlushTimer = null;
+                    void this.flush();
+                }, 0);
+            }
+        }
+    }
+    /**
+     * Throttled update entry point.
+     *
+     * @param throttleMs - Minimum interval between flushes (varies by
+     *   CardKit vs IM patch mode). Passed in by the caller so this
+     *   controller remains business-logic-free.
+     */
+    async throttledUpdate(throttleMs) {
+        if (!this.cardMessageReady())
+            return;
+        const now = Date.now();
+        const elapsed = now - this.lastUpdateTime;
+        if (elapsed >= throttleMs) {
+            this.cancelPendingFlush();
+            if (elapsed > THROTTLE_CONSTANTS.LONG_GAP_THRESHOLD_MS) {
+                // After a long gap, batch briefly so the first visible update
+                // contains meaningful text rather than just 1-2 characters.
+                this.lastUpdateTime = now;
+                this.pendingFlushTimer = setTimeout(() => {
+                    this.pendingFlushTimer = null;
+                    void this.flush();
+                }, THROTTLE_CONSTANTS.BATCH_AFTER_GAP_MS);
+            }
+            else {
+                await this.flush();
+            }
+        }
+        else if (!this.pendingFlushTimer) {
+            // Inside throttle window — schedule a deferred flush
+            const delay = throttleMs - elapsed;
+            this.pendingFlushTimer = setTimeout(() => {
+                this.pendingFlushTimer = null;
+                void this.flush();
+            }, delay);
+        }
+    }
+    // ------------------------------------------------------------------
+    // Internal
+    // ------------------------------------------------------------------
+    /** Overridable gate: subclasses / consumers can set via setCardMessageReady. */
+    _cardMessageReady = false;
+    cardMessageReady() {
+        return this._cardMessageReady;
+    }
+    setCardMessageReady(ready) {
+        this._cardMessageReady = ready;
+        if (ready) {
+            // Initialize the timestamp so the first throttledUpdate sees a
+            // small elapsed time (matching original behavior where
+            // lastCardUpdateTime = Date.now() was set during card creation).
+            this.lastUpdateTime = Date.now();
+        }
+    }
+}

package/src/card/image-resolver.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * ImageResolver — converts image URLs in markdown to Feishu image keys.
+ *
+ * Used by StreamingCardController to asynchronously download and upload
+ * images referenced via `![alt](https://...)` in model-generated markdown,
+ * replacing them with `![alt](img_xxx)` that Feishu cards can render.
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+export interface ImageResolverOptions {
+    cfg: ClawdbotConfig;
+    accountId: string | undefined;
+    /** Called when a previously-pending image upload completes. */
+    onImageResolved: () => void;
+}
+export declare class ImageResolver {
+    /** URL → imageKey for successfully uploaded images. */
+    private readonly resolved;
+    /** URL → upload Promise for in-flight uploads (dedup). */
+    private readonly pending;
+    /** URLs that have already failed — skip retries. */
+    private readonly failed;
+    private readonly cfg;
+    private readonly accountId;
+    private readonly onImageResolved;
+    constructor(opts: ImageResolverOptions);
+    /**
+     * Synchronously resolve image URLs in markdown text.
+     *
+     * - `img_xxx` references are kept as-is.
+     * - URLs with a cached imageKey are replaced inline.
+     * - URLs with an in-flight upload are stripped (will appear after re-flush).
+     * - New URLs trigger an async upload and are stripped for now.
+     */
+    resolveImages(text: string): string;
+    /**
+     * Resolve all image URLs in text synchronously: trigger uploads for new
+     * URLs, wait for all pending uploads, then return text with image keys.
+     */
+    resolveImagesAwait(text: string, timeoutMs: number): Promise<string>;
+    private startUpload;
+    private doUpload;
+}

package/src/card/image-resolver.js

@@ -0,0 +1,112 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * ImageResolver — converts image URLs in markdown to Feishu image keys.
+ *
+ * Used by StreamingCardController to asynchronously download and upload
+ * images referenced via `![alt](https://...)` in model-generated markdown,
+ * replacing them with `![alt](img_xxx)` that Feishu cards can render.
+ */
+import { fetchRemoteImageBuffer, uploadImageLark } from '../messaging/outbound/media';
+import { larkLogger } from '../core/lark-logger';
+const log = larkLogger('card/image-resolver');
+/** Matches complete markdown image syntax: `![alt](value)` */
+const IMAGE_RE = /!\[([^\]]*)\]\(([^)\s]+)\)/g;
+export class ImageResolver {
+    /** URL → imageKey for successfully uploaded images. */
+    resolved = new Map();
+    /** URL → upload Promise for in-flight uploads (dedup). */
+    pending = new Map();
+    /** URLs that have already failed — skip retries. */
+    failed = new Set();
+    cfg;
+    accountId;
+    onImageResolved;
+    constructor(opts) {
+        this.cfg = opts.cfg;
+        this.accountId = opts.accountId;
+        this.onImageResolved = opts.onImageResolved;
+    }
+    /**
+     * Synchronously resolve image URLs in markdown text.
+     *
+     * - `img_xxx` references are kept as-is.
+     * - URLs with a cached imageKey are replaced inline.
+     * - URLs with an in-flight upload are stripped (will appear after re-flush).
+     * - New URLs trigger an async upload and are stripped for now.
+     */
+    resolveImages(text) {
+        if (!text.includes('!['))
+            return text;
+        return text.replace(IMAGE_RE, (fullMatch, alt, value) => {
+            // Already a Feishu image key — keep.
+            if (value.startsWith('img_'))
+                return fullMatch;
+            // Not a remote URL — strip (local paths, data URIs, etc.).
+            if (!value.startsWith('http://') && !value.startsWith('https://'))
+                return '';
+            // Cached — replace with image key.
+            const cached = this.resolved.get(value);
+            if (cached)
+                return `![${alt}](${cached})`;
+            // Already failed — don't retry, strip.
+            if (this.failed.has(value))
+                return '';
+            // Upload in progress — strip for now.
+            if (this.pending.has(value))
+                return '';
+            // New URL — kick off async upload, strip for now.
+            this.startUpload(value);
+            return '';
+        });
+    }
+    /**
+     * Resolve all image URLs in text synchronously: trigger uploads for new
+     * URLs, wait for all pending uploads, then return text with image keys.
+     */
+    async resolveImagesAwait(text, timeoutMs) {
+        // First pass: trigger uploads for any new URLs
+        this.resolveImages(text);
+        if (this.pending.size > 0) {
+            log.info('resolveImagesAwait: waiting for uploads', { count: this.pending.size, timeoutMs });
+            const allUploads = Promise.all(this.pending.values());
+            const timeout = new Promise((resolve) => setTimeout(resolve, timeoutMs));
+            await Promise.race([allUploads, timeout]);
+            if (this.pending.size > 0) {
+                log.warn('resolveImagesAwait: timed out with pending uploads', {
+                    remaining: this.pending.size,
+                });
+            }
+        }
+        // Second pass: replace URLs with resolved image keys
+        return this.resolveImages(text);
+    }
+    startUpload(url) {
+        const uploadPromise = this.doUpload(url);
+        this.pending.set(url, uploadPromise);
+    }
+    async doUpload(url) {
+        try {
+            log.info('uploading image', { url });
+            const buffer = await fetchRemoteImageBuffer(url);
+            const { imageKey } = await uploadImageLark({
+                cfg: this.cfg,
+                image: buffer,
+                imageType: 'message',
+                accountId: this.accountId,
+            });
+            log.info('image uploaded', { url, imageKey });
+            this.resolved.set(url, imageKey);
+            this.pending.delete(url);
+            this.onImageResolved();
+            return imageKey;
+        }
+        catch (err) {
+            log.warn('image upload failed', { url, error: String(err) });
+            this.pending.delete(url);
+            this.failed.add(url);
+            return null;
+        }
+    }
+}

package/src/card/markdown-style.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Markdown 样式优化工具
+ */
+/**
+ * 优化 Markdown 样式：
+ * - 标题降级：H1 → H4，H2~H6 → H5
+ * - 表格前后增加段落间距
+ * - 有序列表：序号后确保只有一个空格
+ * - 无序列表："- " 格式规范化（跳过分隔线 ---）
+ * - 表格：单元格前后补空格，分隔符行规范化，表格前后加空行
+ * - 代码块内容不受影响
+ */
+export declare function optimizeMarkdownStyle(text: string, cardVersion?: number): string;

package/src/card/markdown-style.js

@@ -0,0 +1,97 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Markdown 样式优化工具
+ */
+/**
+ * 优化 Markdown 样式：
+ * - 标题降级：H1 → H4，H2~H6 → H5
+ * - 表格前后增加段落间距
+ * - 有序列表：序号后确保只有一个空格
+ * - 无序列表："- " 格式规范化（跳过分隔线 ---）
+ * - 表格：单元格前后补空格，分隔符行规范化，表格前后加空行
+ * - 代码块内容不受影响
+ */
+export function optimizeMarkdownStyle(text, cardVersion = 2) {
+    try {
+        let r = _optimizeMarkdownStyle(text, cardVersion);
+        r = stripInvalidImageKeys(r);
+        return r;
+    }
+    catch {
+        return text;
+    }
+}
+function _optimizeMarkdownStyle(text, cardVersion = 2) {
+    // ── 1. 提取代码块，用占位符保护，处理后再还原 ─────────────────────
+    const MARK = '___CB_';
+    const codeBlocks = [];
+    let r = text.replace(/```[\s\S]*?```/g, (m) => {
+        return `${MARK}${codeBlocks.push(m) - 1}___`;
+    });
+    // ── 2. 标题降级 ────────────────────────────────────────────────────
+    // 只有当原文档包含 h1~h3 标题时才执行降级
+    // 先处理 H2~H6 → H5，再处理 H1 → H4
+    // 顺序不能颠倒：若先 H1→H4，H4（####）会被后面的 #{2,6} 再次匹配成 H5
+    const hasH1toH3 = /^#{1,3} /m.test(text);
+    if (hasH1toH3) {
+        r = r.replace(/^#{2,6} (.+)$/gm, '##### $1'); // H2~H6 → H5
+        r = r.replace(/^# (.+)$/gm, '#### $1'); // H1 → H4
+    }
+    if (cardVersion >= 2) {
+        // ── 3. 连续标题间增加段落间距 ───────────────────────────────────────
+        r = r.replace(/^(#{4,5} .+)\n{1,2}(#{4,5} )/gm, '$1\n<br>\n$2');
+        // ── 4. 表格前后增加段落间距 ─────────────────────────────────────────
+        // 4a. 非表格行直接跟表格行时，先补一个空行
+        r = r.replace(/^([^|\n].*)\n(\|.+\|)/gm, '$1\n\n$2');
+        // 4b. 表格前：在空行之前插入 <br>（即 \n\n| → \n<br>\n\n| ）
+        r = r.replace(/\n\n((?:\|.+\|[^\S\n]*\n?)+)/g, '\n\n<br>\n\n$1');
+        // 4c. 表格后：在表格块末尾追加 <br>
+        r = r.replace(/((?:^\|.+\|[^\S\n]*\n?)+)/gm, '$1\n<br>\n');
+        // 4d. 表格前是普通文本（非标题、非加粗行）时，只需 <br>，去掉多余空行
+        //     "text\n\n<br>\n\n|" → "text\n<br>\n|"
+        r = r.replace(/^((?!#{4,5} )(?!\*\*).+)\n\n(<br>)\n\n(\|)/gm, '$1\n$2\n$3');
+        // 4d2. 表格前是加粗行时，<br> 紧贴加粗行，空行保留在后面
+        //     "**bold**\n\n<br>\n\n|" → "**bold**\n<br>\n\n|"
+        r = r.replace(/^(\*\*.+)\n\n(<br>)\n\n(\|)/gm, '$1\n$2\n\n$3');
+        // 4e. 表格后是普通文本（非标题、非加粗行）时，只需 <br>，去掉多余空行
+        //     "| row |\n\n<br>\ntext" → "| row |\n<br>\ntext"
+        r = r.replace(/(\|[^\n]*\n)\n(<br>\n)((?!#{4,5} )(?!\*\*))/gm, '$1$2$3');
+        // ── 5. 还原代码块，并在前后追加 <br> ──────────────────────────────
+        codeBlocks.forEach((block, i) => {
+            r = r.replace(`${MARK}${i}___`, `\n<br>\n${block}\n<br>\n`);
+        });
+    }
+    else {
+        // ── 5. 还原代码块（无 <br>）───────────────────────────────────────
+        codeBlocks.forEach((block, i) => {
+            r = r.replace(`${MARK}${i}___`, block);
+        });
+    }
+    // ── 6. 压缩多余空行（3 个以上连续换行 → 2 个）────────────────────
+    r = r.replace(/\n{3,}/g, '\n\n');
+    return r;
+}
+// ---------------------------------------------------------------------------
+// stripInvalidImageKeys
+// ---------------------------------------------------------------------------
+/** Matches complete markdown image syntax: `![alt](value)` */
+const IMAGE_RE = /!\[([^\]]*)\]\(([^)\s]+)\)/g;
+/**
+ * Strip `![alt](value)` where value is not a valid Feishu image key
+ * (`img_xxx`). Prevents CardKit error 200570.
+ *
+ * HTTP URLs are stripped as well — ImageResolver should have already
+ * replaced them with `img_xxx` keys before this point. This serves
+ * as a safety net for any unresolved URLs.
+ */
+function stripInvalidImageKeys(text) {
+    if (!text.includes('!['))
+        return text;
+    return text.replace(IMAGE_RE, (fullMatch, _alt, value) => {
+        if (value.startsWith('img_'))
+            return fullMatch;
+        return ''; // strip all non-img_ image references (URLs, local paths, etc.)
+    });
+}