@zhin.js/adapter-lark 1.1.4 → 1.1.5

package/lib/stream-proxy.js

@@ -0,0 +1,17 @@
+import { Agent } from 'node:https';
+import tls from 'node:tls';
+import { getLogger } from '@zhin.js/logger';
+/** WSClient uses this agent only for WSS; discovery/OpenAPI stay unchanged. */
+export function createLarkStreamAgent(proxy) {
+    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, path: undefined, host: '127.0.0.1', port: proxy.port,
+            servername: hostname, rejectUnauthorized: true });
+    };
+    return agent;
+}

package/lib/web-api-proxy.d.ts

@@ -0,0 +1,11 @@
+import type { LarkFetch } from './endpoint.js';
+export interface LarkWebApiProxy {
+    readonly port: number;
+}
+export declare function validateLarkWebApiProxy(value: LarkWebApiProxy): void;
+/** Per-endpoint fetch dispatcher; URL/Host/SNI remain the official Feishu identity. */
+export declare function createLarkWebApiTransport(proxy: LarkWebApiProxy): {
+    fetch: LarkFetch;
+    reopen(): void;
+    close(): Promise<void>;
+};

package/lib/web-api-proxy.js

@@ -0,0 +1,48 @@
+import { Agent, fetch as dispatcherFetch } from 'undici';
+import tls from 'node:tls';
+export function validateLarkWebApiProxy(value) {
+    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) {
+    validateLarkWebApiProxy(proxy);
+    const port = proxy.port;
+    const sockets = new Set();
+    let active = true;
+    let dispatcher;
+    const fetch = 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) => 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 });
+    };
+    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(); },
+    };
+}

package/lib/webhook.d.ts

@@ -1,6 +1,7 @@
 /**
  * Lark/Feishu webhook HTTP: verification → signature → challenge/event → admit.
  */
+import type { LarkCardAction } from './cards.js';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { type LarkMessage, type ResolvedLarkConfig } from './protocol.js';
@@ -9,6 +10,7 @@ export interface LarkWebhookHandler {
     readonly isOpen: boolean;
     admitPlatform(name: string, event: unknown): void;
     admit(msg: LarkMessage): void;
+    admitCardAction?(event: LarkCardAction): void;
 }
 export declare function registerLarkWebhookRoutes(http: HttpHost, handler: LarkWebhookHandler): HttpRouteRegistration[];
 export declare function handleLarkWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: LarkWebhookHandler): Promise<void>;

package/lib/webhook.js

@@ -12,8 +12,18 @@ export function registerLarkWebhookRoutes(http, handler) {
 export async function handleLarkWebhookRequest(request, response, handler) {
     try {
         const rawBody = await readTextBody(request);
+        let event;
+        try {
+            event = JSON.parse(rawBody);
+        }
+        catch {
+            response.writeHead(200, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ code: 0, msg: 'success' }));
+            return;
+        }
         if (handler.config.verificationToken) {
-            const token = headerValue(request.headers, 'x-lark-request-token');
+            const bodyToken = event.header?.token ?? event.token;
+            const token = typeof bodyToken === 'string' ? bodyToken : headerValue(request.headers, 'x-lark-request-token');
             if (!verifyToken(token, handler.config.verificationToken)) {
                 logger.warn(formatCompact({ op: 'webhook', ok: false, error: 'invalid verification token' }));
                 response.writeHead(403, { 'Content-Type': 'text/plain' });
@@ -35,15 +45,6 @@ export async function handleLarkWebhookRequest(request, response, handler) {
                 return;
             }
         }
-        let event;
-        try {
-            event = JSON.parse(rawBody);
-        }
-        catch {
-            response.writeHead(200, { 'Content-Type': 'application/json' });
-            response.end(JSON.stringify({ code: 0, msg: 'success' }));
-            return;
-        }
         if (handler.isOpen) {
             const eventName = event.type === 'event_callback'
                 ? String(event.event?.type ?? event.type)
@@ -55,6 +56,8 @@ export async function handleLarkWebhookRequest(request, response, handler) {
             response.end(JSON.stringify({ challenge: event.challenge }));
             return;
         }
+        if (event.header?.event_type === 'card.action.trigger' && handler.isOpen)
+            handler.admitCardAction?.(event.event);
         if (event.type === 'event_callback' && event.event?.message && handler.isOpen) {
             const message = {
                 ...event.event.message,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-lark",
-  "version": "1.1.4",
-  "description": "Zhin.js Lark/Feishu (飞书) adapter for Plugin Runtime (HTTP webhook)",
+  "version": "1.1.5",
+  "description": "Zhin.js Lark/Feishu adapter (HTTP webhook and WebSocket long connection)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -34,24 +34,26 @@
     "directory": "plugins/adapters/lark"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.15",
-    "@zhin.js/agent-feature": "1.1.2",
-    "@zhin.js/core": "1.1.39",
+    "undici": "6.28.0",
+    "@larksuiteoapi/node-sdk": "^1.67.0",
+    "@zhin.js/adapter": "1.1.16",
+    "@zhin.js/agent-feature": "1.1.3",
+    "@zhin.js/core": "1.1.40",
     "@zhin.js/feature-kit": "1.1.2",
-    "@zhin.js/host-http": "1.1.2",
-    "@zhin.js/im-contract": "1.1.2",
+    "@zhin.js/host-http": "1.1.3",
+    "@zhin.js/im-contract": "1.1.3",
     "@zhin.js/logger": "1.1.1",
-    "@zhin.js/skill": "1.1.2",
-    "@zhin.js/tool": "1.1.2"
+    "@zhin.js/skill": "1.1.3",
+    "@zhin.js/tool": "1.1.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.15",
-    "@zhin.js/command": "^1.1.3",
-    "@zhin.js/core": "^1.1.39",
-    "@zhin.js/host-http": "^1.1.2",
+    "@zhin.js/adapter": "^1.1.16",
+    "@zhin.js/command": "^1.1.4",
+    "@zhin.js/core": "^1.1.40",
+    "@zhin.js/host-http": "^1.1.3",
     "@zhin.js/permission": "^1.1.3",
-    "zhin.js": "^1.1.4"
+    "zhin.js": "^1.1.5"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -69,7 +71,7 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "zhin.js": "1.1.4"
+    "zhin.js": "1.1.5"
   },
   "files": [
     "adapters",

package/schema.json

@@ -89,6 +89,50 @@
           "id": {
             "type": "string",
             "description": "Lark bot name"
+          },
+          "mode": {
+            "type": "string",
+            "enum": [
+              "webhook",
+              "websocket"
+            ],
+            "default": "webhook"
+          },
+          "streamProxy": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "port": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              },
+              "serverName": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[^\\s/:@?#]+$"
+              }
+            },
+            "required": [
+              "port",
+              "serverName"
+            ],
+            "description": "WSS故障验收：仅TCP固定loopback，保留TLS身份"
+          },
+          "webApiProxy": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "port"
+            ],
+            "properties": {
+              "port": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              }
+            },
+            "description": "默认关闭；仅飞书出站API的loopback TLS故障代理，保留官方Host/SNI和证书校验，与streamProxy独立"
           }
         },
         "required": [
@@ -102,6 +146,29 @@
       "type": "string",
       "default": "",
       "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    },
+    "mode": {
+      "type": "string",
+      "enum": [
+        "webhook",
+        "websocket"
+      ],
+      "default": "webhook"
+    },
+    "webApiProxy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "port"
+      ],
+      "properties": {
+        "port": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65535
+        }
+      },
+      "description": "默认关闭；仅飞书出站API的loopback TLS故障代理，保留官方Host/SNI和证书校验，与streamProxy独立"
     }
   },
   "required": [

package/src/cards.ts

@@ -0,0 +1,69 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import type { LarkSendBody, LarkWireSegment } from './protocol.js';
+
+/** Feishu JSON card v1: ordered native rich text, link and button components. */
+export function formatLarkCard(items: Array<string | LarkWireSegment>): LarkSendBody {
+  const elements: unknown[] = [];
+  let replyTo: string | undefined;
+  for (const item of items) {
+    if (typeof item === 'string') { elements.push({ tag: 'div', text: { tag: 'plain_text', content: item } }); continue; }
+    const data = item.data ?? {};
+    switch (item.type) {
+      case 'reply': replyTo = String(data.message_id ?? '') || undefined; break;
+      case 'text': elements.push({ tag: 'div', text: { tag: 'plain_text', content: String(data.text ?? data.content ?? '') } }); break;
+      case 'markdown': elements.push({ tag: 'div', text: { tag: 'lark_md', content: String(data.content ?? data.text ?? '') } }); break;
+      case 'image': {
+        const media = data.media as { kind?: string; value?: string } | undefined;
+        if (media?.kind !== 'file' || !media.value) throw unsupported();
+        elements.push({ tag: 'img', img_key: media.value, alt: { tag: 'plain_text', content: 'Image' } }); break;
+      }
+      case 'share': {
+        const url = String(data.url ?? '');
+        if (!/^https?:\/\//.test(url)) throw unsupported();
+        elements.push({ tag: 'div', text: { tag: 'plain_text', content: String(data.title ?? url) } });
+        if (data.description) elements.push({ tag: 'div', text: { tag: 'plain_text', content: String(data.description) } });
+        elements.push({ tag: 'action', actions: [{ tag: 'button', text: { tag: 'plain_text', content: '打开链接' }, url }] }); break;
+      }
+      case 'keyboard': {
+        const rows = data.rows as Array<Array<{ id?: string; label?: string; payload?: string; url?: string }>> | undefined;
+        if (!Array.isArray(rows) || rows.length === 0) throw unsupported();
+        for (const row of rows) {
+          if (!Array.isArray(row) || !row.length || row.length > 5) throw unsupported();
+          const actions = row.map(button => {
+            if (!button.label || (!button.payload && !button.url)) throw unsupported();
+            return { tag: 'button', text: { tag: 'plain_text', content: button.label },
+              ...(button.url ? { url: button.url } : { value: { zhin_payload: button.payload, zhin_button_id: button.id } }) };
+          });
+          elements.push({ tag: 'action', actions });
+        }
+        break;
+      }
+      default: throw unsupported();
+    }
+  }
+  // JSON 1.0 lark_md does not render inline code. Use the SDK's JSON 2.0
+  // markdown component for Markdown cards; keep validated v1 action cards.
+  const hasMarkdown = items.some(item => typeof item !== 'string' && item.type === 'markdown');
+  const hasActions = items.some(item => typeof item !== 'string' && ['share', 'keyboard'].includes(item.type));
+  if (hasMarkdown && hasActions) throw new EndpointDeliveryError('unsupported_operation', 'Mixed Markdown and action cards require JSON 2.0 action support', 'not_sent');
+  if (hasMarkdown) {
+    const bodyElements = elements.map(element => {
+      const row = element as { tag: string; text?: { tag: string; content: string } };
+      if (row.tag !== 'div') return element;
+      const text = row.text!;
+      return { tag: 'markdown', content: text.tag === 'lark_md' ? text.content : text.content.replace(/[\\`*_{}[\]()#+.!|>~-]/g, '\\$&') };
+    });
+    return { msg_type: 'interactive', content: JSON.stringify({ schema: '2.0', body: { elements: bodyElements } }), ...(replyTo ? { replyTo } : {}) };
+  }
+  return { msg_type: 'interactive', content: JSON.stringify({ config: { wide_screen_mode: true }, elements }), ...(replyTo ? { replyTo } : {}) };
+}
+function unsupported() { return new EndpointDeliveryError('unsupported_operation', 'Unsupported or malformed Lark card segment', 'not_sent'); }
+
+export interface LarkCardAction {
+  readonly token?: string;
+  readonly context?: { readonly open_message_id?: string; readonly open_chat_id?: string };
+  readonly open_message_id?: string;
+  readonly open_chat_id?: string;
+  readonly operator?: { readonly open_id?: string; readonly user_id?: string };
+  readonly action?: { readonly tag?: string; readonly value?: { readonly zhin_payload?: unknown; readonly zhin_button_id?: unknown } };
+}