@zhin.js/adapter-lark 1.0.97 → 1.1.2

package/lib/protocol.js

@@ -0,0 +1,272 @@
+/**
+ * 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 { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('lark');
+export function resolveLarkConfig(config) {
+    const id = requiredEndpointField(config.id, 'id');
+    const appId = requiredEndpointField(config.appId, 'appId');
+    const appSecret = requiredEndpointField(config.appSecret, 'appSecret');
+    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(/\/$/, '');
+    const encryptKey = config.encryptKey;
+    const verificationToken = config.verificationToken;
+    return {
+        context: 'lark',
+        id,
+        appId,
+        appSecret,
+        ...(encryptKey ? { encryptKey } : {}),
+        ...(verificationToken ? { verificationToken } : {}),
+        webhookPath,
+        apiBaseUrl,
+        isFeishu,
+    };
+}
+function requiredEndpointField(value, field) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError(`Lark endpoint requires a non-empty ${field}`);
+    }
+    return value.trim();
+}
+export function normalizeWebhookPath(path) {
+    const trimmed = path.trim() || '/lark/webhook';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+export function resolveChatType(chatId, chatType) {
+    // 优先使用事件里的 chat_type：p2p 会话的 chat_id 同样以 oc_ 开头，不能靠前缀判断
+    if (chatType === 'group')
+        return 'group';
+    if (chatType === 'p2p')
+        return 'private';
+    return chatId?.startsWith('oc_') ? 'group' : 'private';
+}
+/**
+ * 入站归一化 → ConversationRef：`chat_type` 为 'group' 的会话映射为 group，
+ * p2p 单聊映射为 private；id 一律为平台 chat_id。Lark 无 guild/频道容器，
+ * 不产生 `parent`。
+ */
+export function larkInboundConversation(endpointKey, msg) {
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind: resolveChatType(msg.chat_id, msg.chat_type),
+        id: msg.chat_id || 'unknown',
+    };
+}
+export function resolveSender(msg) {
+    return msg.sender?.sender_id?.open_id
+        || msg.sender?.sender_id?.user_id
+        || 'unknown';
+}
+export function generateMessageId(msg) {
+    return msg.message_id || `${msg.create_time ?? Date.now()}`;
+}
+/** Build inbound text for OutboundMessageService.receive. */
+export function formatInboundContent(msg) {
+    if (!msg.content || !msg.message_type)
+        return '';
+    try {
+        const parsed = JSON.parse(msg.content);
+        switch (msg.message_type) {
+            case 'text':
+                return typeof parsed.text === 'string' ? parsed.text : '';
+            case 'image':
+                return '[image]';
+            case 'file': {
+                const name = typeof parsed.file_name === 'string' ? parsed.file_name : '';
+                return name ? `[file: ${name}]` : '[file]';
+            }
+            case 'audio':
+                return '[audio]';
+            case 'video':
+                return '[video]';
+            case 'sticker':
+                return '[sticker]';
+            case 'post':
+            case 'interactive':
+                return `[${msg.message_type}]`;
+            case 'rich_text':
+                return '[rich_text]';
+            default:
+                return `[${msg.message_type}]`;
+        }
+    }
+    catch {
+        return '[消息解析失败]';
+    }
+}
+/** 验签时间戳时效窗口（防重放）。 */
+export const LARK_SIGNATURE_MAX_AGE_MS = 5 * 60_000;
+export function verifySignature(encryptKey, timestamp, nonce, body, signature, nowMs = Date.now()) {
+    try {
+        // 时效窗口 ±5min，超出直接拒绝（timestamp 为秒）
+        const ts = Number(timestamp);
+        if (!Number.isFinite(ts) || Math.abs(nowMs - ts * 1000) > LARK_SIGNATURE_MAX_AGE_MS) {
+            return false;
+        }
+        const stringToSign = `${timestamp}${nonce}${encryptKey}${body}`;
+        const calculated = createHash('sha256').update(stringToSign).digest('hex');
+        const a = Buffer.from(calculated);
+        const b = Buffer.from(signature);
+        if (a.length !== b.length)
+            return false;
+        return timingSafeEqual(a, b);
+    }
+    catch {
+        return false;
+    }
+}
+/** timing-safe 比较 webhook verification token（长度不同快速失败）。 */
+export function verifyToken(token, expected) {
+    try {
+        const a = Buffer.from(token);
+        const b = Buffer.from(expected);
+        if (a.length !== b.length)
+            return false;
+        return timingSafeEqual(a, b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Wire-encode an already-rendered outbound payload into Lark im/v1 message body.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundBody(payload) {
+    if (typeof payload === 'string') {
+        return {
+            msg_type: 'text',
+            content: JSON.stringify({ text: payload }),
+        };
+    }
+    const items = Array.isArray(payload)
+        ? payload
+        : payload && typeof payload === 'object' && 'type' in payload
+            ? [payload]
+            : [];
+    const hasMarkdown = items.some((item) => typeof item !== 'string' && item.type === 'markdown');
+    if (items.length === 0) {
+        const text = payload == null
+            ? ''
+            : typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload);
+        return {
+            msg_type: 'text',
+            content: JSON.stringify({ text }),
+        };
+    }
+    const textParts = [];
+    let media = null;
+    for (const item of items) {
+        if (typeof item === 'string') {
+            textParts.push(item);
+            continue;
+        }
+        const data = item.data ?? {};
+        switch (item.type) {
+            case 'text':
+                textParts.push(String(data.content ?? data.text ?? ''));
+                break;
+            case 'markdown':
+                textParts.push(String(data.content ?? data.text ?? ''));
+                break;
+            case 'at':
+                textParts.push(`<at user_id="${String(data.id ?? '')}">${String(data.name || data.id || '')}</at>`);
+                break;
+            case 'image':
+                if (!media) {
+                    // image_key 唯一来源：canonical MediaRef kind=file（endpoint 上传物化产物或调用方既有平台引用）
+                    const ref = data.media;
+                    if (isMediaRef(ref) && ref.kind === 'file') {
+                        media = {
+                            msg_type: 'image',
+                            content: JSON.stringify({ image_key: ref.value }),
+                        };
+                    }
+                    else {
+                        logger.warn(formatCompact({
+                            op: 'lark_outbound_media_dropped',
+                            type: 'image',
+                            reason: isMediaRef(ref) ? 'unmaterialized_media' : 'missing_media_ref',
+                        }));
+                    }
+                }
+                break;
+            case 'file':
+                if (!media) {
+                    const ref = data.media;
+                    if (isMediaRef(ref) && ref.kind === 'file') {
+                        media = {
+                            msg_type: 'file',
+                            content: JSON.stringify({ file_key: ref.value }),
+                        };
+                    }
+                    else {
+                        logger.warn(formatCompact({
+                            op: 'lark_outbound_media_dropped',
+                            type: 'file',
+                            reason: isMediaRef(ref) ? 'unmaterialized_media' : 'missing_media_ref',
+                        }));
+                    }
+                }
+                break;
+            case 'card':
+                if (!media) {
+                    media = {
+                        msg_type: 'interactive',
+                        content: JSON.stringify(data),
+                    };
+                }
+                break;
+            default:
+                textParts.push(`[${item.type}]`);
+        }
+    }
+    if (media)
+        return media;
+    if (hasMarkdown) {
+        return {
+            msg_type: 'interactive',
+            content: JSON.stringify({
+                elements: [{
+                        tag: 'div',
+                        text: { tag: 'lark_md', content: textParts.join('') },
+                    }],
+            }),
+        };
+    }
+    return {
+        msg_type: 'text',
+        content: JSON.stringify({ text: textParts.join('') }),
+    };
+}
+export function headerValue(headers, name) {
+    const value = headers[name] ?? headers[name.toLowerCase()];
+    if (Array.isArray(value))
+        return value[0] ?? '';
+    return value ?? '';
+}
+export async function readTextBody(request, options = {}) {
+    const limit = options.limit ?? 1_048_576;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > limit) {
+            request.destroy();
+            throw new Error(`Request body exceeds ${limit} bytes`);
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}

package/lib/webhook.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Lark/Feishu webhook HTTP: verification → signature → challenge/event → admit.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { type LarkMessage, type ResolvedLarkConfig } from './protocol.js';
+export interface LarkWebhookHandler {
+    readonly config: ResolvedLarkConfig;
+    readonly isOpen: boolean;
+    admitPlatform(name: string, event: unknown): void;
+    admit(msg: LarkMessage): 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

@@ -0,0 +1,73 @@
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { headerValue, readTextBody, verifySignature, verifyToken, } from './protocol.js';
+const logger = getLogger('lark');
+export function registerLarkWebhookRoutes(http, handler) {
+    const path = handler.config.webhookPath;
+    return [
+        http.route('POST', path, async (request, response) => {
+            await handleLarkWebhookRequest(request, response, handler);
+        }, { summary: 'Lark/Feishu event webhook', tags: ['lark'] }),
+    ];
+}
+export async function handleLarkWebhookRequest(request, response, handler) {
+    try {
+        const rawBody = await readTextBody(request);
+        if (handler.config.verificationToken) {
+            const token = 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' });
+                response.end('Forbidden');
+                return;
+            }
+        }
+        if (handler.config.encryptKey) {
+            const timestamp = headerValue(request.headers, 'x-lark-request-timestamp');
+            const nonce = headerValue(request.headers, 'x-lark-request-nonce');
+            const signature = headerValue(request.headers, 'x-lark-signature');
+            if (!timestamp
+                || !nonce
+                || !signature
+                || !verifySignature(handler.config.encryptKey, timestamp, nonce, rawBody, signature)) {
+                logger.warn(formatCompact({ op: 'webhook', ok: false, error: 'invalid signature' }));
+                response.writeHead(403, { 'Content-Type': 'text/plain' });
+                response.end('Forbidden');
+                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)
+                : String(event.type ?? 'event');
+            handler.admitPlatform(eventName, event);
+        }
+        if (event.type === 'url_verification') {
+            response.writeHead(200, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ challenge: event.challenge }));
+            return;
+        }
+        if (event.type === 'event_callback' && event.event?.message && handler.isOpen) {
+            const message = {
+                ...event.event.message,
+                sender: event.event.message.sender ?? event.event.sender,
+            };
+            handler.admit(message);
+        }
+        response.writeHead(200, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ code: 0, msg: 'success' }));
+    }
+    catch (error) {
+        logger.error('Webhook error:', error);
+        response.writeHead(500, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ code: -1, msg: 'Internal Server Error' }));
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-lark",
-  "version": "1.0.97",
-  "description": "Zhin.js adapter for Lark/Feishu (飞书)",
+  "version": "1.1.2",
+  "description": "Zhin.js Lark/Feishu (飞书) adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -34,41 +34,96 @@
     "directory": "plugins/adapters/lark"
   },
   "dependencies": {
-    "axios": "^1.16.1"
-  },
-  "devDependencies": {
-    "@types/koa": "^3.0.3",
-    "@types/node": "^25.9.1",
-    "typescript": "^6.0.3",
-    "zhin.js": "1.0.93"
+    "@zhin.js/adapter": "1.1.14",
+    "@zhin.js/agent-feature": "1.1.1",
+    "@zhin.js/core": "1.1.37",
+    "@zhin.js/feature-kit": "1.1.1",
+    "@zhin.js/host-http": "1.1.1",
+    "@zhin.js/im-contract": "1.1.1",
+    "@zhin.js/logger": "1.1.1",
+    "@zhin.js/skill": "1.1.1",
+    "@zhin.js/tool": "1.1.1"
   },
   "peerDependencies": {
-    "zhin.js": "1.0.93",
-    "@zhin.js/host-router": "0.0.3"
+    "zod": "^4.0.0",
+    "@zhin.js/adapter": "^1.1.14",
+    "@zhin.js/command": "^1.1.1",
+    "@zhin.js/core": "^1.1.37",
+    "@zhin.js/host-http": "^1.1.1",
+    "@zhin.js/permission": "^1.1.1",
+    "zhin.js": "^1.1.2"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/host-router": {
-      "optional": false
+    "@zhin.js/command": {
+      "optional": true
+    },
+    "zhin.js": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "zhin.js": "1.1.2"
+  },
   "files": [
+    "adapters",
+    "commands",
+    "plugin.js",
+    "schema.json",
     "src",
     "lib",
-    "client",
-    "dist",
-    "skills",
-    "plugin.yml",
+    "tools",
+    "agents",
     "README.md",
-    "node",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "PERMITS.md"
   ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/tool",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/skill",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/agent-feature",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "pnpm build:node",
+    "build": "tsc",
     "clean": "rimraf lib",
-    "build:node": "tsc"
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/lark/tests"
   }
 }

package/plugin.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { createEndpointRuntimeState } from 'zhin.js/adapter';
+import { definePlugin } from 'zhin.js';
+import { permissionHostToken } from '@zhin.js/permission';
+import { checkLarkPlatformPermit } from "./lib/platform-permit.js";
+import { larkRuntimeStateToken } from "./lib/lark-runtime-state.js";
+export default definePlugin({
+    name: 'lark',
+    metadata: {
+        displayName: 'Lark/Feishu (飞书) Adapter',
+    },
+    setup(context) {
+        context.resources.provide(larkRuntimeStateToken, createEndpointRuntimeState());
+        if (context.resources.has(permissionHostToken)) {
+            const host = context.resources.use(permissionHostToken);
+            return host.registerPlatform('lark', checkLarkPlatformPermit);
+        }
+    },
+});

package/schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "webhookPath": {
+      "type": "string",
+      "default": "/lark/webhook"
+    },
+    "apiBaseUrl": {
+      "type": "string"
+    },
+    "isFeishu": {
+      "type": "boolean",
+      "default": true
+    },
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（Lark/Feishu open_id or user_id；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted Lark/Feishu open_id or user_id"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
+    "endpoints": {
+      "type": "array",
+      "minItems": 1,
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（Lark/Feishu open_id or user_id）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted Lark/Feishu open_id or user_id"
+            },
+            "description": "本 endpoint 的 trusted 列表"
+          },
+          "appId": {
+            "type": "string",
+            "description": "Lark app ID"
+          },
+          "appSecret": {
+            "type": "string",
+            "description": "Lark app secret"
+          },
+          "encryptKey": {
+            "type": "string",
+            "description": "Lark encrypt key"
+          },
+          "verificationToken": {
+            "type": "string",
+            "description": "Lark verification token"
+          },
+          "webhookPath": {
+            "type": "string"
+          },
+          "apiBaseUrl": {
+            "type": "string"
+          },
+          "isFeishu": {
+            "type": "boolean"
+          },
+          "commandPrefix": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string",
+            "description": "Lark bot name"
+          }
+        },
+        "required": [
+          "id",
+          "appId",
+          "appSecret"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,16 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+import type { LarkClient } from './endpoint.js';
+import type { LarkEventBody } from './protocol.js';
+
+export type LarkClientEventMap = Record<string, LarkEventBody>;
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly lark: {
+      readonly client: LarkClient;
+      readonly events: LarkClientEventMap;
+    };
+  }
+}
+
+export const larkClient = defineEndpointClient<LarkClient, LarkClientEventMap>('lark');