@zhin.js/adapter-lark 1.1.4 → 1.1.6

package/src/endpoint.ts

@@ -1,10 +1,16 @@
-import { Endpoint } from 'zhin.js/adapter';
+import { createLarkWebApiTransport } from './web-api-proxy.js';
+import type { LarkCardAction } from './cards.js';
+import { EndpointDeliveryError, type ConversationRef } 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 {
+  Endpoint,
+  createEndpointLifecycle,
+  type EndpointLifecycle,
+  type EndpointTransportState,
   createRecallEndpointControl,
   type EndpointControl,
   type EndpointGroup,
@@ -32,6 +38,7 @@ import {
   type ResolvedLarkConfig,
 } from './protocol.js';
 import { registerLarkWebhookRoutes } from './webhook.js';
+import { createLarkLongConnection, type LarkLongConnectionFactory } from './long-connection.js';
 
 /** 出站 HTTP 调用统一 30s 超时。 */
 const OUTBOUND_TIMEOUT_MS = 30_000;
@@ -53,7 +60,8 @@ export type LarkFetch = (
 
 export interface LarkEndpointOptions {
   readonly id: CapabilityId;
-  readonly http: HttpHost;
+  readonly http?: HttpHost;
+  readonly longConnectionFactory?: LarkLongConnectionFactory;
   readonly config: ResolvedLarkConfig;
   readonly fetch?: LarkFetch;
 }
@@ -110,6 +118,7 @@ export class LarkEndpoint extends Endpoint<LarkClient> {
 
   readonly #options: LarkEndpointOptions;
   readonly #fetch: LarkFetch;
+  readonly #webApiTransport?: ReturnType<typeof createLarkWebApiTransport>;
   /**
    * Console 社交面语义端口。Lark OpenAPI 仅接读取类列表能力：
    * - listGroups：GET /im/v1/chats（bot 所在群列表，分页归一为 {group_id: chat_id, name}）
@@ -142,12 +151,20 @@ export class LarkEndpoint extends Endpoint<LarkClient> {
   #refreshPromise: Promise<string> | null = null;
   #open = false;
   #started = false;
+  readonly #lifecycle: EndpointLifecycle;
+  readonly #cardSources = new Map<string, { conversation: ConversationRef; time: number }>();
+  readonly #seen = new Map<string, number>();
+  #startupGeneration = 0;
+  readonly #pendingInbound: LarkMessage[] = [];
 
   constructor(options: LarkEndpointOptions) {
     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. */
@@ -159,10 +176,35 @@ export class LarkEndpoint extends Endpoint<LarkClient> {
     return this.#options.config;
   }
 
+  get transportState(): EndpointTransportState | undefined {
+    return this.config.mode === 'websocket' ? this.#lifecycle.state : undefined;
+  }
+
   async start(): Promise<void> {
     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({
@@ -173,6 +215,8 @@ export class LarkEndpoint extends Endpoint<LarkClient> {
         }));
       }
       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,
@@ -188,6 +232,7 @@ export class LarkEndpoint extends Endpoint<LarkClient> {
 
   open(): void {
     this.#open = true;
+    for (const message of this.#pendingInbound.splice(0)) this.admit(message);
   }
 
   close(): void {
@@ -196,42 +241,68 @@ export class LarkEndpoint extends Endpoint<LarkClient> {
 
   async stop(): Promise<void> {
     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 }: EndpointSendRequest): Promise<string> {
-    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 as string) || `${Date.now()}`;
-    this.#logger.debug(formatCompact({ op: 'send', to: conversation.id,
-      id: messageId,
-    }));
-    return messageId;
   }
 
   async recallMessage(messageId: string): Promise<void> {
     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: unknown): Promise<unknown> {
     if (!Array.isArray(payload)) return payload;
@@ -243,10 +314,7 @@ export class LarkEndpoint extends Endpoint<LarkClient> {
       const media = readOutboundImageMedia(data);
       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 } },
@@ -254,33 +322,36 @@ export class LarkEndpoint extends Endpoint<LarkClient> {
     }));
   }
 
-  /** POST /im/v1/images（image_type=message），返回 image_key；失败返回 null。 */
-  async uploadImage(media: Parameters<typeof resolveMediaBinary>[0]): Promise<string | null> {
-    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() as LarkApiResponse;
-      if (data.code === 0) {
-        return (data.data?.image_key as string) || null;
-      }
-      throw new Error(`Image upload failed: ${data.msg}`);
-    } catch (error) {
-      this.#logger.error('Failed to upload image:', error);
-      return null;
-    }
+  /** Upload must succeed before issuing a message; dropped media is never confirmed. */
+  async uploadImage(media: Parameters<typeof resolveMediaBinary>[0]): Promise<string> {
+    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) as LarkApiResponse | 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: LarkMessage): void {
     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,
@@ -301,6 +372,28 @@ export class LarkEndpoint extends Endpoint<LarkClient> {
     });
   }
 
+  /** Only correlate callbacks to a card actually sent by this endpoint. */
+  admitCardAction(event: LarkCardAction): void {
+    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: string, event: unknown): void {
     if (!this.#open) return;
     void this.emitPlatform(name, event).catch((error) => {
@@ -542,11 +635,15 @@ export class LarkEndpoint extends Endpoint<LarkClient> {
       body: body && method !== 'GET' ? JSON.stringify(body) : undefined,
       signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
     });
+    const data = await response.json().catch(() => undefined) as LarkApiResponse | 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() as LarkApiResponse;
+    if (platformCode === undefined) throw new LarkRequestError(response.status, undefined, false);
+    if (platformCode !== 0) throw new LarkRequestError(response.status, platformCode, true);
+    return data!;
   }
 
   async #ensureAccessToken(): Promise<void> {
@@ -585,6 +682,24 @@ export class LarkEndpoint extends Endpoint<LarkClient> {
       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: unknown): string {
+  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 {
+  readonly status: number;
+  readonly platformCode: number | undefined;
+  constructor(status: number, platformCode: number | undefined, rejected: boolean) {
+    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/src/index.ts

@@ -49,3 +49,10 @@ export {
   handleLarkWebhookRequest,
   type LarkWebhookHandler,
 } from './webhook.js';
+
+export {
+  createLarkLongConnection,
+  type LarkLongConnection,
+  type LarkLongConnectionFactory,
+  type LarkLongConnectionOptions,
+} from './long-connection.js';

package/src/long-connection.ts

@@ -0,0 +1,87 @@
+import type { LarkCardAction } from './cards.js';
+import * as lark from '@larksuiteoapi/node-sdk';
+import { createLarkStreamAgent } from './stream-proxy.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 const createLarkLongConnection: LarkLongConnectionFactory = ({ config, receive, cardAction, disconnected }) => {
+  let cancelled = false;
+  let ready = false;
+  let settleReady!: () => void;
+  let settleError!: (error: Error) => void;
+  const connected = new Promise<void>((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: LarkCardAction) => { if (!cancelled) cardAction?.(event as LarkCardAction); 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: ReturnType<typeof setInterval> | undefined;
+  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/src/protocol.ts

@@ -1,3 +1,4 @@
+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.
@@ -5,14 +6,19 @@
 
 import { createHash, timingSafeEqual } from 'node:crypto';
 import type { IncomingMessage } from 'node:http';
-import { isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
+import { formatLarkCard } from './cards.js';
+
 const logger = getLogger('lark');
 
 /** 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;
@@ -23,8 +29,11 @@ export interface LarkEndpointConfig {
 }
 
 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;
@@ -100,14 +109,20 @@ export interface LarkWireSegment {
 }
 
 export interface LarkSendBody {
+  readonly replyTo?: string;
   readonly msg_type: string;
   readonly content: string;
 }
 
 export function resolveLarkConfig(config: LarkEndpointConfig): ResolvedLarkConfig {
+  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
@@ -116,10 +131,14 @@ export function resolveLarkConfig(config: LarkEndpointConfig): ResolvedLarkConfi
   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,
@@ -266,6 +285,7 @@ export function formatOutboundBody(payload: unknown): LarkSendBody {
     : payload && typeof payload === 'object' && 'type' in (payload as object)
       ? [payload as LarkWireSegment]
       : [];
+  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) {
@@ -282,6 +302,7 @@ export function formatOutboundBody(payload: unknown): LarkSendBody {
 
   const textParts: string[] = [];
   let media: LarkSendBody | null = null;
+  let replyTo: string | undefined;
 
   for (const item of items) {
     if (typeof item === 'string') {
@@ -290,6 +311,12 @@ export function formatOutboundBody(payload: unknown): LarkSendBody {
     }
     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;
@@ -349,9 +376,35 @@ export function formatOutboundBody(payload: unknown): LarkSendBody {
     }
   }
 
-  if (media) return media;
+  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: Record<string, string>[][] = [];
+    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, ...(replyTo ? { replyTo } : {}) };
   if (hasMarkdown) {
     return {
+      ...(replyTo ? { replyTo } : {}),
       msg_type: 'interactive',
       content: JSON.stringify({
         elements: [{
@@ -362,6 +415,7 @@ export function formatOutboundBody(payload: unknown): LarkSendBody {
     };
   }
   return {
+    ...(replyTo ? { replyTo } : {}),
     msg_type: 'text',
     content: JSON.stringify({ text: textParts.join('') }),
   };

package/src/stream-proxy.ts

@@ -0,0 +1,20 @@
+import { Agent } from 'node:https';
+import tls from 'node:tls';
+import { getLogger } from '@zhin.js/logger';
+
+export interface LarkStreamProxy { readonly port: number; readonly serverName: string }
+
+/** WSClient uses this agent only for WSS; discovery/OpenAPI stay unchanged. */
+export function createLarkStreamAgent(proxy: LarkStreamProxy): Agent {
+  const agent = new Agent({ keepAlive: false });
+  agent.createConnection = options => {
+    const hostname = String(options.hostname ?? options.host ?? '');
+    if (hostname !== proxy.serverName || Number(options.port ?? 443) !== 443) {
+      getLogger('lark').warn(`Stream proxy rejected gateway hostname: ${hostname}`);
+      throw new Error('Lark Stream proxy gateway identity changed; update fixed upstream before retrying');
+    }
+    return tls.connect({ ...options as tls.ConnectionOptions, path: undefined, host: '127.0.0.1', port: proxy.port,
+      servername: hostname, rejectUnauthorized: true });
+  };
+  return agent;
+}

package/src/web-api-proxy.ts

@@ -0,0 +1,51 @@
+import { Agent, fetch as dispatcherFetch } from 'undici';
+import tls from 'node:tls';
+import type { LarkFetch } from './endpoint.js';
+
+export interface LarkWebApiProxy { readonly port: number }
+
+export function validateLarkWebApiProxy(value: LarkWebApiProxy): void {
+  if (!value || typeof value !== 'object' || Object.keys(value).some(key => key !== 'port')
+    || !Number.isInteger(value.port) || value.port < 1 || value.port > 65535) {
+    throw new TypeError('Invalid Lark webApiProxy: only a loopback port is allowed');
+  }
+}
+
+/** Per-endpoint fetch dispatcher; URL/Host/SNI remain the official Feishu identity. */
+export function createLarkWebApiTransport(proxy: LarkWebApiProxy) {
+  validateLarkWebApiProxy(proxy);
+  const port = proxy.port;
+  const sockets = new Set<tls.TLSSocket>();
+  let active = true;
+  let dispatcher: Agent | undefined;
+  const fetch: LarkFetch = async (url, init) => {
+    const target = new URL(url);
+    if (target.origin !== 'https://open.feishu.cn' || target.username || target.password
+      || target.hash || !target.pathname.startsWith('/open-apis/')) {
+      throw new TypeError('Lark Web API proxy rejected destination identity');
+    }
+    if (!active) throw new Error('Lark Web API proxy transport is stopped');
+    dispatcher ??= new Agent({ connect(options, callback) {
+      if (options.hostname !== 'open.feishu.cn' || options.protocol !== 'https:' || Number(options.port || 443) !== 443) {
+        callback(new Error('Lark Web API proxy rejected destination identity'), null);
+        return;
+      }
+      const socket = tls.connect({ host: '127.0.0.1', port,
+        servername: 'open.feishu.cn', rejectUnauthorized: true });
+      sockets.add(socket);
+      socket.once('close', () => sockets.delete(socket));
+      socket.setTimeout(10_000, () => socket.destroy(new Error('Lark Web API TLS connection timeout')));
+      const failed = (error: Error) => callback(error, null);
+      socket.once('error', failed);
+      socket.once('secureConnect', () => { socket.setTimeout(0); socket.removeListener('error', failed); callback(null, socket); });
+    } });
+    // Pair fetch and its dispatcher from the same Undici version; Node's bundled
+    // handler protocol may differ (notably Node 26 versus Undici 6).
+    return dispatcherFetch(url, { ...init, redirect: 'error', dispatcher } as Parameters<typeof dispatcherFetch>[1]);
+  };
+  return {
+    fetch,
+    reopen() { active = true; },
+    async close() { active = false; for (const socket of sockets) socket.destroy(new Error('Lark Web API proxy transport stopped')); const previous = dispatcher; dispatcher = undefined; await previous?.destroy(); },
+  };
+}