@zhin.js/adapter-lark 1.1.4 → 1.1.5

package/lib/endpoint.js

@@ -1,14 +1,16 @@
-import { Endpoint } from 'zhin.js/adapter';
+import { createLarkWebApiTransport } from './web-api-proxy.js';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 /**
  * LarkEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
  */
 import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
-import { createRecallEndpointControl, } from 'zhin.js/adapter';
+import { Endpoint, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { buildImageUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
 import { formatInboundContent, formatOutboundBody, generateMessageId, larkInboundConversation, resolveChatType, resolveSender, } from './protocol.js';
 import { registerLarkWebhookRoutes } from './webhook.js';
+import { createLarkLongConnection } from './long-connection.js';
 /** 出站 HTTP 调用统一 30s 超时。 */
 const OUTBOUND_TIMEOUT_MS = 30_000;
 /** Feishu/Lark OpenAPI client surface carried by every Endpoint event. */
@@ -46,6 +48,7 @@ export class LarkEndpoint extends Endpoint {
     #logger;
     #options;
     #fetch;
+    #webApiTransport;
     /**
      * Console 社交面语义端口。Lark OpenAPI 仅接读取类列表能力：
      * - listGroups：GET /im/v1/chats（bot 所在群列表，分页归一为 {group_id: chat_id, name}）
@@ -76,11 +79,20 @@ export class LarkEndpoint extends Endpoint {
     #refreshPromise = null;
     #open = false;
     #started = false;
+    #lifecycle;
+    #cardSources = new Map();
+    #seen = new Map();
+    #startupGeneration = 0;
+    #pendingInbound = [];
     constructor(options) {
         super();
         this.#logger = getAdapterLogger('lark', options.config.id);
         this.#options = options;
-        this.#fetch = options.fetch ?? globalThis.fetch;
+        if (options.config.webApiProxy && options.fetch)
+            throw new TypeError('Lark webApiProxy cannot be combined with an injected fetch');
+        this.#webApiTransport = options.config.webApiProxy ? createLarkWebApiTransport(options.config.webApiProxy) : undefined;
+        this.#fetch = this.#webApiTransport?.fetch ?? options.fetch ?? globalThis.fetch;
+        this.#lifecycle = createEndpointLifecycle({ name: options.config.id });
     }
     /** Used by webhook handler. */
     get isOpen() {
@@ -89,11 +101,41 @@ export class LarkEndpoint extends Endpoint {
     get config() {
         return this.#options.config;
     }
+    get transportState() {
+        return this.config.mode === 'websocket' ? this.#lifecycle.state : undefined;
+    }
     async start() {
         if (this.#started)
             return;
+        this.#webApiTransport?.reopen();
         this.#started = true;
+        const generation = ++this.#startupGeneration;
         try {
+            if (this.config.mode === 'websocket') {
+                await this.#lifecycle.start(async (handle) => {
+                    let active = true;
+                    const transport = (this.#options.longConnectionFactory ?? createLarkLongConnection)({
+                        config: this.config,
+                        receive: (message) => {
+                            if (!active || !this.#started || generation !== this.#startupGeneration)
+                                return;
+                            if (this.#open)
+                                this.admit(message);
+                            else if (this.#pendingInbound.length < 100)
+                                this.#pendingInbound.push(message);
+                            else
+                                this.#logger.warn('lark_inbound_startup_buffer_full');
+                        },
+                        cardAction: (event) => { if (active && this.#open && generation === this.#startupGeneration)
+                            this.admitCardAction(event); },
+                        disconnected: () => { if (!active)
+                            return; active = false; transport.close(); handle.notifyClosed(); },
+                    });
+                    handle.onForceClose(() => { active = false; transport.close(); });
+                    await transport.connect();
+                });
+                return;
+            }
             if (!this.#options.config.encryptKey && !this.#options.config.verificationToken) {
                 // encryptKey / verificationToken 都未配置时 webhook 完全无鉴权，任何人可伪造事件
                 this.#logger.warn(formatCompact({
@@ -104,6 +146,10 @@ export class LarkEndpoint extends Endpoint {
                 }));
             }
             await this.#refreshAccessToken();
+            if (!this.#started || generation !== this.#startupGeneration)
+                return;
+            if (!this.#options.http)
+                throw new Error('Lark webhook mode requires HttpHost');
             this.#routeReleases.push(...registerLarkWebhookRoutes(this.#options.http, this));
             this.#logger.debug(formatCompact({
                 endpoint: this.#options.config.id,
@@ -119,47 +165,81 @@ export class LarkEndpoint extends Endpoint {
     }
     open() {
         this.#open = true;
+        for (const message of this.#pendingInbound.splice(0))
+            this.admit(message);
     }
     close() {
         this.#open = false;
     }
     async stop() {
         this.#open = false;
+        this.#pendingInbound.length = 0;
+        this.#cardSources.clear();
+        this.#started = false;
+        ++this.#startupGeneration;
+        await this.#lifecycle.stop();
+        await this.#webApiTransport?.close();
         for (const release of this.#routeReleases.splice(0))
             release();
         this.#started = false;
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
     async send({ conversation, payload }) {
-        const materialized = await this.#materializeOutboundMedia(payload);
-        const content = formatOutboundBody(materialized);
-        const data = await this.#request('/im/v1/messages', {
-            method: 'POST',
-            params: { receive_id_type: 'chat_id' },
-            body: {
-                receive_id: conversation.id,
-                msg_type: content.msg_type,
-                content: content.content,
-            },
-        });
-        if (data.code !== 0) {
-            throw new Error(`Failed to send message: ${data.msg}`);
+        try {
+            const materialized = await this.#materializeOutboundMedia(payload);
+            const content = formatOutboundBody(materialized);
+            const data = await this.#request(content.replyTo
+                ? `/im/v1/messages/${encodeURIComponent(content.replyTo)}/reply`
+                : '/im/v1/messages', {
+                method: 'POST',
+                ...(content.replyTo ? {} : { params: { receive_id_type: 'chat_id' } }),
+                body: {
+                    ...(content.replyTo ? {} : { receive_id: conversation.id }),
+                    msg_type: content.msg_type,
+                    content: content.content,
+                },
+            });
+            if (typeof data.code === 'number' && data.code !== 0) {
+                throw new EndpointDeliveryError('platform_rejected', `Lark rejected message (code=${data.code})`, 'rejected');
+            }
+            if (data.code !== 0)
+                throw new EndpointDeliveryError('delivery_unconfirmed', 'Malformed platform response', 'unknown');
+            const messageId = requireMessageId(data.data?.message_id);
+            if (content.msg_type === 'interactive') {
+                const now = Date.now();
+                for (const [id, source] of this.#cardSources)
+                    if (now - source.time > 300_000)
+                        this.#cardSources.delete(id);
+                this.#cardSources.set(messageId, { conversation, time: now });
+                if (this.#cardSources.size > 10_000)
+                    this.#cardSources.delete(this.#cardSources.keys().next().value);
+            }
+            this.#logger.debug(formatCompact({ op: 'send', to: conversation.id,
+                id: messageId,
+            }));
+            return messageId;
+        }
+        catch (error) {
+            this.#logger.warn(formatCompact({
+                op: 'lark_send_failed',
+                status: error instanceof LarkRequestError ? error.status : undefined,
+                platform_code: error instanceof LarkRequestError ? error.platformCode : undefined,
+                outcome: error instanceof EndpointDeliveryError ? error.disposition : 'unknown',
+            }));
+            if (error instanceof EndpointDeliveryError)
+                throw error;
+            throw new EndpointDeliveryError('delivery_unconfirmed', 'Outbound request outcome is unknown', 'unknown', { cause: error });
         }
-        const messageId = data.data?.message_id || `${Date.now()}`;
-        this.#logger.debug(formatCompact({ op: 'send', to: conversation.id,
-            id: messageId,
-        }));
-        return messageId;
     }
     async recallMessage(messageId) {
         if (!messageId || messageId.startsWith('outbound:'))
             return;
-        await this.#request(`/im/v1/messages/${messageId}`, { method: 'DELETE' });
+        await this.#request(`/im/v1/messages/${encodeURIComponent(messageId)}`, { method: 'DELETE' });
     }
     /**
      * im/v1 消息 image 段只接受 image_key：canonical MediaRef（base64/本地路径/URL）
      * 先经 /im/v1/images 物化，产物回写为 MediaRef kind=file（平台不透明引用）；
-     * 上传失败降级为文本（alt 优先），不阻断发送。
+     * 上传失败阻止消息发送并保留拒绝或未知分类。
      */
     async #materializeOutboundMedia(payload) {
         if (!Array.isArray(payload))
@@ -175,44 +255,51 @@ export class LarkEndpoint extends Endpoint {
             if (!media)
                 return item;
             const imageKey = await this.uploadImage(media);
-            if (!imageKey) {
-                const alt = typeof data.alt === 'string' && data.alt ? data.alt : '[image]';
-                return { type: 'text', data: { text: alt } };
-            }
+            if (!imageKey)
+                throw new EndpointDeliveryError('delivery_unconfirmed', 'Lark image upload returned no image key', 'unknown');
             return {
                 type: 'image',
                 data: { media: { kind: 'file', value: imageKey } },
             };
         }));
     }
-    /** POST /im/v1/images（image_type=message），返回 image_key；失败返回 null。 */
+    /** Upload must succeed before issuing a message; dropped media is never confirmed. */
     async uploadImage(media) {
-        try {
-            await this.#ensureAccessToken();
-            const binary = await resolveMediaBinary(media);
-            const form = buildImageUploadForm(binary);
-            const url = `${this.#options.config.apiBaseUrl}/im/v1/images`;
-            const response = await this.#fetch(url, {
-                method: 'POST',
-                headers: { Authorization: `Bearer ${this.#accessToken.token}` },
-                body: form,
-                signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
-            });
-            const data = await response.json();
-            if (data.code === 0) {
-                return data.data?.image_key || null;
-            }
-            throw new Error(`Image upload failed: ${data.msg}`);
-        }
-        catch (error) {
-            this.#logger.error('Failed to upload image:', error);
-            return null;
-        }
+        await this.#ensureAccessToken();
+        const binary = await resolveMediaBinary(media);
+        const form = buildImageUploadForm(binary);
+        const response = await this.#fetch(`${this.#options.config.apiBaseUrl}/im/v1/images`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${this.#accessToken.token}` },
+            body: form,
+            signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
+        });
+        const data = await response.json().catch(() => undefined);
+        const code = typeof data?.code === 'number' && Number.isFinite(data.code) ? data.code : undefined;
+        if (!response.ok)
+            throw new LarkRequestError(response.status, code, response.status >= 400 && response.status < 500 && response.status !== 408);
+        if (code !== 0)
+            throw new LarkRequestError(response.status, code, code !== undefined);
+        const key = data?.data?.image_key;
+        if (typeof key !== 'string' || !key.trim())
+            throw new LarkRequestError(response.status, code, false);
+        return key;
     }
     /** Test / internal: admit a parsed message when open (non-webhook path). */
     admit(msg) {
         if (!this.#open)
             return;
+        if (msg.message_id) {
+            const now = Date.now();
+            for (const [id, time] of this.#seen)
+                if (now - time > 300_000)
+                    this.#seen.delete(id);
+            if (this.#seen.has(msg.message_id))
+                return;
+            this.#seen.set(msg.message_id, now);
+            if (this.#seen.size > 10_000)
+                this.#seen.delete(this.#seen.keys().next().value);
+        }
         const conversation = larkInboundConversation(String(this.#options.id), msg);
         void this.emit('message.receive', {
             conversation,
@@ -232,6 +319,32 @@ export class LarkEndpoint extends Endpoint {
             }));
         });
     }
+    /** Only correlate callbacks to a card actually sent by this endpoint. */
+    admitCardAction(event) {
+        if (!this.#open)
+            return;
+        const sourceId = event.context?.open_message_id ?? event.open_message_id;
+        const chatId = event.context?.open_chat_id ?? event.open_chat_id;
+        const sender = event.operator?.open_id ?? event.operator?.user_id;
+        const payload = event.action?.value?.zhin_payload;
+        if (!sourceId || !chatId || !sender || typeof payload !== 'string' || event.action?.tag !== 'button')
+            return;
+        const source = this.#cardSources.get(sourceId);
+        if (!source || source.conversation.id !== chatId || Date.now() - source.time > 300_000)
+            return;
+        const dedup = `card:${event.token ?? `${sourceId}:${sender}:${payload}`}`;
+        if (this.#seen.has(dedup))
+            return;
+        this.#seen.set(dedup, Date.now());
+        if (this.#seen.size > 10_000)
+            this.#seen.delete(this.#seen.keys().next().value);
+        const conversation = source.conversation;
+        void this.emit('message.receive', {
+            conversation, message: { conversation, id: dedup }, content: '',
+            segments: [{ type: 'action', data: { payload } }], sender: { id: sender }, endpointId: this.config.id,
+            metadata: Object.freeze({ eventType: 'card.action.trigger', sourceMessageId: sourceId }),
+        }).catch(() => this.#logger.warn('lark_card_action_receive_failed'));
+    }
     admitPlatform(name, event) {
         if (!this.#open)
             return;
@@ -453,11 +566,17 @@ export class LarkEndpoint extends Endpoint {
             body: body && method !== 'GET' ? JSON.stringify(body) : undefined,
             signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
         });
+        const data = await response.json().catch(() => undefined);
+        const platformCode = typeof data?.code === 'number' && Number.isFinite(data.code) ? data.code : undefined;
         if (!response.ok) {
-            const text = await response.text().catch(() => '');
-            throw new Error(`Lark API error ${response.status}: ${text}`);
+            const rejected = response.status >= 400 && response.status < 500 && response.status !== 408;
+            throw new LarkRequestError(response.status, platformCode, rejected);
         }
-        return await response.json();
+        if (platformCode === undefined)
+            throw new LarkRequestError(response.status, undefined, false);
+        if (platformCode !== 0)
+            throw new LarkRequestError(response.status, platformCode, true);
+        return data;
     }
     async #ensureAccessToken() {
         const now = Date.now();
@@ -492,6 +611,21 @@ export class LarkEndpoint extends Endpoint {
             this.#logger.debug('Access token refreshed successfully');
             return;
         }
-        throw new Error(`Failed to get access token: ${data.msg} (${data.code})`);
+        throw new LarkRequestError(response.status, typeof data.code === 'number' ? data.code : undefined, response.ok && typeof data.code === 'number' && data.code !== 0 || response.status >= 400 && response.status < 500 && response.status !== 408);
+    }
+}
+function requireMessageId(value) {
+    if (typeof value === 'string' && value.trim().length > 0)
+        return value;
+    throw new EndpointDeliveryError('delivery_unconfirmed', 'Platform did not return a real message ID', 'unknown');
+}
+/** Carries only safe numerical diagnostics, never response bodies or credentials. */
+class LarkRequestError extends EndpointDeliveryError {
+    status;
+    platformCode;
+    constructor(status, platformCode, rejected) {
+        super(rejected ? 'platform_rejected' : 'delivery_unconfirmed', `Lark request failed (status=${status}${platformCode === undefined ? '' : `, code=${platformCode}`})`, rejected ? 'rejected' : 'unknown');
+        this.status = status;
+        this.platformCode = platformCode;
     }
 }

package/lib/index.d.ts

@@ -4,3 +4,4 @@ export { checkLarkPlatformPermit, larkGroupPermitResolver, normalizeLarkSenderFo
 export { LarkClient, LarkEndpoint, type LarkClientApi, type LarkEndpointOptions, type LarkFetch, } from './endpoint.js';
 export { buildImageUploadForm, readOutboundImageMedia, resolveMediaBinary, type MediaBinary, } from './media-upload.js';
 export { registerLarkWebhookRoutes, handleLarkWebhookRequest, type LarkWebhookHandler, } from './webhook.js';
+export { createLarkLongConnection, type LarkLongConnection, type LarkLongConnectionFactory, type LarkLongConnectionOptions, } from './long-connection.js';

package/lib/index.js

@@ -4,3 +4,4 @@ export { checkLarkPlatformPermit, larkGroupPermitResolver, normalizeLarkSenderFo
 export { LarkClient, LarkEndpoint, } from './endpoint.js';
 export { buildImageUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
 export { registerLarkWebhookRoutes, handleLarkWebhookRequest, } from './webhook.js';
+export { createLarkLongConnection, } from './long-connection.js';

package/lib/long-connection.d.ts

@@ -0,0 +1,16 @@
+import type { LarkCardAction } from './cards.js';
+import type { LarkMessage, ResolvedLarkConfig } from './protocol.js';
+export interface LarkLongConnection {
+    /** Resolves only after the transport handshake, never merely after SDK start(). */
+    connect(): Promise<void>;
+    close(): void;
+}
+export interface LarkLongConnectionOptions {
+    readonly config: ResolvedLarkConfig;
+    readonly receive: (message: LarkMessage) => void;
+    readonly cardAction?: (event: LarkCardAction) => void;
+    readonly disconnected: () => void;
+}
+export type LarkLongConnectionFactory = (options: LarkLongConnectionOptions) => LarkLongConnection;
+/** The SDK owns wire framing / acknowledgements / ping; Zhin owns reconnect. */
+export declare const createLarkLongConnection: LarkLongConnectionFactory;

package/lib/long-connection.js

@@ -0,0 +1,88 @@
+import * as lark from '@larksuiteoapi/node-sdk';
+import { createLarkStreamAgent } from './stream-proxy.js';
+/** The SDK owns wire framing / acknowledgements / ping; Zhin owns reconnect. */
+export const createLarkLongConnection = ({ config, receive, cardAction, disconnected }) => {
+    let cancelled = false;
+    let ready = false;
+    let settleReady;
+    let settleError;
+    const connected = new Promise((resolve, reject) => {
+        settleReady = resolve;
+        settleError = reject;
+    });
+    // close-before-connect must never create an unhandled rejection.
+    connected.catch(() => { });
+    const agent = config.streamProxy ? createLarkStreamAgent(config.streamProxy) : undefined;
+    const client = new lark.WSClient({
+        appId: config.appId,
+        appSecret: config.appSecret,
+        agent,
+        domain: config.isFeishu ? lark.Domain.Feishu : lark.Domain.Lark,
+        autoReconnect: false,
+        loggerLevel: lark.LoggerLevel.error,
+        onReady: () => {
+            if (cancelled) {
+                client.close({ force: true });
+                return;
+            }
+            ready = true;
+            settleReady();
+        },
+        onError: () => {
+            if (cancelled)
+                return;
+            if (ready)
+                disconnected();
+            else
+                settleError(new Error('Lark long connection failed'));
+        },
+    });
+    const dispatcher = new lark.EventDispatcher({}).register({
+        'card.action.trigger': (event) => { if (!cancelled)
+            cardAction?.(event); return {}; },
+        'im.message.receive_v1': (event) => {
+            if (!cancelled)
+                receive({ ...event.message, sender: event.sender });
+            // No downstream send is awaited: SDK ACK remains within its 3-second window.
+        },
+    });
+    let healthTimer;
+    return {
+        async connect() {
+            if (cancelled)
+                throw new Error('Lark long connection stopped');
+            const deadline = setTimeout(() => settleError(new Error('Lark long connection handshake timed out')), 30_000);
+            try {
+                await client.start({ eventDispatcher: dispatcher });
+                await connected;
+                if (cancelled) {
+                    client.close({ force: true });
+                    return;
+                }
+                healthTimer = setInterval(() => {
+                    if (!cancelled && ready && client.getConnectionStatus().state !== 'connected') {
+                        ready = false;
+                        disconnected();
+                    }
+                }, 1_000);
+                healthTimer.unref();
+            }
+            catch (error) {
+                client.close({ force: true });
+                agent?.destroy();
+                throw error;
+            }
+            finally {
+                clearTimeout(deadline);
+            }
+        },
+        close() {
+            cancelled = true;
+            if (healthTimer)
+                clearInterval(healthTimer);
+            settleError(new Error('Lark long connection stopped'));
+            client.close({ force: true });
+            agent?.destroy();
+        },
+    };
+};

package/lib/protocol.d.ts

@@ -1,12 +1,11 @@
-/**
- * Lark/Feishu protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
- * Canonicalization is owned by gateway/core before endpoint.send.
- */
 import type { IncomingMessage } from 'node:http';
 import { type ConversationRef } from '@zhin.js/im-contract';
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
 export interface LarkEndpointConfig {
+    readonly webApiProxy?: import('./web-api-proxy.js').LarkWebApiProxy;
+    readonly streamProxy?: import('./stream-proxy.js').LarkStreamProxy;
     readonly id: string;
+    readonly mode?: 'webhook' | 'websocket';
     readonly appId: string;
     readonly appSecret: string;
     readonly encryptKey?: string;
@@ -16,8 +15,11 @@ export interface LarkEndpointConfig {
     readonly isFeishu?: boolean;
 }
 export interface ResolvedLarkConfig {
+    readonly webApiProxy?: import('./web-api-proxy.js').LarkWebApiProxy;
+    readonly streamProxy?: import('./stream-proxy.js').LarkStreamProxy;
     readonly context: 'lark';
     readonly id: string;
+    readonly mode: 'webhook' | 'websocket';
     readonly appId: string;
     readonly appSecret: string;
     readonly encryptKey?: string;
@@ -87,6 +89,7 @@ export interface LarkWireSegment {
     readonly data?: Record<string, unknown>;
 }
 export interface LarkSendBody {
+    readonly replyTo?: string;
     readonly msg_type: string;
     readonly content: string;
 }

package/lib/protocol.js

@@ -1,25 +1,40 @@
+import { validateLarkWebApiProxy } from './web-api-proxy.js';
 /**
  * Lark/Feishu protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import { createHash, timingSafeEqual } from 'node:crypto';
-import { isMediaRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
+import { formatLarkCard } from './cards.js';
 const logger = getLogger('lark');
 export function resolveLarkConfig(config) {
+    if (config.streamProxy && (!Number.isInteger(config.streamProxy.port) || config.streamProxy.port < 1 || config.streamProxy.port > 65535
+        || typeof config.streamProxy.serverName !== 'string' || !config.streamProxy.serverName || /[\s/:@?#]/.test(config.streamProxy.serverName)))
+        throw new TypeError('Invalid Lark streamProxy port/serverName');
+    if (config.webApiProxy)
+        validateLarkWebApiProxy(config.webApiProxy);
     const id = requiredEndpointField(config.id, 'id');
     const appId = requiredEndpointField(config.appId, 'appId');
     const appSecret = requiredEndpointField(config.appSecret, 'appSecret');
+    const mode = config.mode ?? 'webhook';
+    if (mode !== 'webhook' && mode !== 'websocket')
+        throw new TypeError('Lark mode must be webhook or websocket');
     const isFeishu = config.isFeishu ?? true;
     const webhookPath = normalizeWebhookPath(config.webhookPath ?? '/lark/webhook');
     const defaultBase = isFeishu
         ? 'https://open.feishu.cn/open-apis'
         : 'https://open.larksuite.com/open-apis';
     const apiBaseUrl = (config.apiBaseUrl ?? defaultBase).replace(/\/$/, '');
+    if (config.webApiProxy && (!isFeishu || apiBaseUrl !== 'https://open.feishu.cn/open-apis'))
+        throw new TypeError('Lark webApiProxy requires the official Feishu API origin');
     const encryptKey = config.encryptKey;
     const verificationToken = config.verificationToken;
     return {
+        ...(config.webApiProxy ? { webApiProxy: config.webApiProxy } : {}),
+        ...(config.streamProxy ? { streamProxy: config.streamProxy } : {}),
         context: 'lark',
+        mode,
         id,
         appId,
         appSecret,
@@ -152,6 +167,8 @@ export function formatOutboundBody(payload) {
         : payload && typeof payload === 'object' && 'type' in payload
             ? [payload]
             : [];
+    if (items.some(item => typeof item !== 'string' && ['markdown', 'share', 'keyboard'].includes(item.type)))
+        return formatLarkCard(items);
     const hasMarkdown = items.some((item) => typeof item !== 'string' && item.type === 'markdown');
     if (items.length === 0) {
         const text = payload == null
@@ -166,6 +183,7 @@ export function formatOutboundBody(payload) {
     }
     const textParts = [];
     let media = null;
+    let replyTo;
     for (const item of items) {
         if (typeof item === 'string') {
             textParts.push(item);
@@ -173,6 +191,13 @@ export function formatOutboundBody(payload) {
         }
         const data = item.data ?? {};
         switch (item.type) {
+            case 'share':
+            case 'keyboard':
+                throw new EndpointDeliveryError('unsupported_operation', 'Lark canonical share cards and native keyboards are not implemented', 'not_sent');
+            case 'reply':
+                if (typeof data.message_id === 'string' && data.message_id.trim())
+                    replyTo = data.message_id;
+                break;
             case 'text':
                 textParts.push(String(data.content ?? data.text ?? ''));
                 break;
@@ -231,10 +256,45 @@ export function formatOutboundBody(payload) {
                 textParts.push(`[${item.type}]`);
         }
     }
+    const imageCount = items.filter((item) => typeof item !== 'string' && item.type === 'image').length;
+    if (imageCount > 0 && (textParts.some((text) => text.length > 0) || imageCount > 1)
+        && !items.some((item) => typeof item !== 'string' && (item.type === 'file' || item.type === 'card'))) {
+        const rows = [];
+        for (const item of items) {
+            if (typeof item === 'string') {
+                if (item)
+                    rows.push([{ tag: 'text', text: item }]);
+                continue;
+            }
+            const data = item.data ?? {};
+            if (item.type === 'reply')
+                continue;
+            if (item.type === 'image') {
+                const ref = data.media;
+                if (isMediaRef(ref) && ref.kind === 'file')
+                    rows.push([{ tag: 'img', image_key: ref.value }]);
+            }
+            else if (item.type === 'at' || item.type === 'mention') {
+                rows.push([{ tag: 'at', user_id: String(data.target ?? data.id ?? ''), user_name: String(data.name ?? data.target ?? data.id ?? '') }]);
+            }
+            else {
+                const text = item.type === 'text' || item.type === 'markdown'
+                    ? String(data.content ?? data.text ?? '') : `[${item.type}]`;
+                if (text)
+                    rows.push([{ tag: 'text', text }]);
+            }
+        }
+        return {
+            ...(replyTo ? { replyTo } : {}),
+            msg_type: 'post',
+            content: JSON.stringify({ zh_cn: { title: '', content: rows } }),
+        };
+    }
     if (media)
-        return media;
+        return { ...media, ...(replyTo ? { replyTo } : {}) };
     if (hasMarkdown) {
         return {
+            ...(replyTo ? { replyTo } : {}),
             msg_type: 'interactive',
             content: JSON.stringify({
                 elements: [{
@@ -245,6 +305,7 @@ export function formatOutboundBody(payload) {
         };
     }
     return {
+        ...(replyTo ? { replyTo } : {}),
         msg_type: 'text',
         content: JSON.stringify({ text: textParts.join('') }),
     };

package/lib/stream-proxy.d.ts

@@ -0,0 +1,7 @@
+import { Agent } from 'node:https';
+export interface LarkStreamProxy {
+    readonly port: number;
+    readonly serverName: string;
+}
+/** WSClient uses this agent only for WSS; discovery/OpenAPI stay unchanged. */
+export declare function createLarkStreamAgent(proxy: LarkStreamProxy): Agent;