@zhin.js/adapter-lark 6.0.2 → 6.0.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @zhin.js/adapter-lark
 
+## 6.0.3
+
+### Patch Changes
+
+- Updated dependencies [afc0e66]
+- Updated dependencies [2e41ad5]
+- Updated dependencies [9f57124]
+  - @zhin.js/core@1.5.2
+  - @zhin.js/adapter@1.1.5
+  - @zhin.js/im-contract@1.0.1
+  - @zhin.js/plugin-runtime@1.1.3
+  - @zhin.js/command@1.0.7
+  - @zhin.js/host-http@1.0.6
+  - @zhin.js/agent@1.1.3
+  - zhin.js@6.0.2
+
 ## 6.0.2
 
 ### Patch Changes

package/README.md

@@ -24,8 +24,8 @@ pnpm add @zhin.js/adapter-lark
 - `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
-入站：`gateway.receive({ adapter, target: chat_id, content: text, sender, metadata })`  
-出站：`send({ target, payload })` → `im/v1/messages`
+入站：`gateway.receive({ conversation, message: { conversation, id }, content: text, sender, metadata })`  
+出站：`send({ conversation, payload })` → `im/v1/messages`
 
 入站 `metadata.mentioned`：**未接线**。消息事件的 `mentions[]` 元素含 `id.open_id`，但本适配器拿不到 bot 自身的 open_id——配置（`appId` / `appSecret` / `name` 等）不含 bot open_id，代码也未调用 `bot/v3/info` 获取应用信息，故无可靠判据比对 mentions。
 

package/lib/endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -40,10 +40,7 @@ export declare class LarkEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     recallMessage(messageId: string): Promise<void>;
     /** POST /im/v1/images（image_type=message），返回 image_key；失败返回 null。 */
     uploadImage(media: Parameters<typeof resolveMediaBinary>[0]): Promise<string | null>;

package/lib/endpoint.js

@@ -6,7 +6,7 @@ import { basename } from 'node:path';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { registerLarkAgentEndpoint } from './lark-agent-deps.js';
 import { buildImageUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
-import { formatInboundContent, formatOutboundBody, generateMessageId, resolveChatType, resolveSender, resolveTarget, } from './protocol.js';
+import { formatInboundContent, formatOutboundBody, generateMessageId, larkInboundConversation, resolveChatType, resolveSender, } from './protocol.js';
 import { registerLarkWebhookRoutes } from './webhook.js';
 const logger = getLogger('lark');
 /** 出站 HTTP 调用统一 30s 超时。 */
@@ -99,14 +99,14 @@ export class LarkEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    async send({ target, payload }) {
+    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: target,
+                receive_id: conversation.id,
                 msg_type: content.msg_type,
                 content: content.content,
             },
@@ -118,7 +118,7 @@ export class LarkEndpoint {
         logger.debug(formatCompact({
             op: 'send',
             endpoint: this.#options.config.name,
-            to: target,
+            to: conversation.id,
             id: messageId,
         }));
         return messageId;
@@ -185,13 +185,12 @@ export class LarkEndpoint {
     admit(msg) {
         if (!this.#open)
             return;
-        const target = resolveTarget(msg);
+        const conversation = larkInboundConversation(String(this.#options.id), msg);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: generateMessageId(msg) },
             content: formatInboundContent(msg),
             sender: resolveSender(msg),
-            id: generateMessageId(msg),
             metadata: Object.freeze({
                 messageType: msg.message_type,
                 chatType: resolveChatType(msg.chat_id, msg.chat_type),
@@ -200,7 +199,7 @@ export class LarkEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'lark_gateway_receive_failed',
-                target,
+                conversation: conversation.id,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { formatInboundContent, formatOutboundBody, generateMessageId, headerValue, normalizeWebhookPath, readTextBody, resolveChatType, resolveLarkConfig, resolveSender, resolveTarget, verifySignature, type AccessToken, type LarkAdapterConfig, type LarkApiResponse, type LarkEventBody, type LarkMessage, type LarkSendBody, type LarkWireSegment, type ResolvedLarkConfig, } from './protocol.js';
+export { formatInboundContent, formatOutboundBody, generateMessageId, headerValue, larkInboundConversation, normalizeWebhookPath, readTextBody, resolveChatType, resolveLarkConfig, resolveSender, verifySignature, type AccessToken, type LarkAdapterConfig, type LarkApiResponse, type LarkEventBody, type LarkMessage, type LarkSendBody, type LarkWireSegment, type ResolvedLarkConfig, } from './protocol.js';
 export { getLarkAgentDeps, registerLarkAgentEndpoint, setLarkAgentDeps, type LarkAgentDeps, type LarkAgentEndpoint, } from './lark-agent-deps.js';
 export { checkLarkPlatformPermit, larkGroupPermitResolver, normalizeLarkSenderForPermit, platformPermit, registerLarkPlatformPermitChecker, } from './platform-permit.js';
 export { LarkEndpoint, type LarkEndpointOptions, type LarkFetch, } from './endpoint.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { formatInboundContent, formatOutboundBody, generateMessageId, headerValue, normalizeWebhookPath, readTextBody, resolveChatType, resolveLarkConfig, resolveSender, resolveTarget, verifySignature, } from './protocol.js';
+export { formatInboundContent, formatOutboundBody, generateMessageId, headerValue, larkInboundConversation, normalizeWebhookPath, readTextBody, resolveChatType, resolveLarkConfig, resolveSender, verifySignature, } from './protocol.js';
 export { getLarkAgentDeps, registerLarkAgentEndpoint, setLarkAgentDeps, } from './lark-agent-deps.js';
 export { checkLarkPlatformPermit, larkGroupPermitResolver, normalizeLarkSenderForPermit, platformPermit, registerLarkPlatformPermitChecker, } from './platform-permit.js';
 export { LarkEndpoint, } from './endpoint.js';

package/lib/protocol.d.ts

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import type { IncomingMessage } from 'node:http';
+import type { ConversationRef } from '@zhin.js/im-contract';
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface LarkAdapterConfig {
     readonly name?: string;
@@ -96,7 +97,12 @@ export interface LarkSendBody {
 export declare function resolveLarkConfig(config?: LarkAdapterConfig): ResolvedLarkConfig;
 export declare function normalizeWebhookPath(path: string): string;
 export declare function resolveChatType(chatId?: string, chatType?: string): 'group' | 'private';
-export declare function resolveTarget(msg: LarkMessage): string;
+/**
+ * 入站归一化 → ConversationRef：`chat_type` 为 'group' 的会话映射为 group，
+ * p2p 单聊映射为 private；id 一律为平台 chat_id。Lark 无 guild/频道容器，
+ * 不产生 `parent`。
+ */
+export declare function larkInboundConversation(endpointId: string, msg: LarkMessage): ConversationRef;
 export declare function resolveSender(msg: LarkMessage): string;
 export declare function generateMessageId(msg: LarkMessage): string;
 /** Build inbound text for MessageGateway.receive. */

package/lib/protocol.js

@@ -49,8 +49,17 @@ export function resolveChatType(chatId, chatType) {
         return 'private';
     return chatId?.startsWith('oc_') ? 'group' : 'private';
 }
-export function resolveTarget(msg) {
-    return msg.chat_id || 'unknown';
+/**
+ * 入站归一化 → ConversationRef：`chat_type` 为 'group' 的会话映射为 group，
+ * p2p 单聊映射为 private；id 一律为平台 chat_id。Lark 无 guild/频道容器，
+ * 不产生 `parent`。
+ */
+export function larkInboundConversation(endpointId, msg) {
+    return {
+        endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+        kind: resolveChatType(msg.chat_id, msg.chat_type),
+        id: msg.chat_id || 'unknown',
+    };
 }
 export function resolveSender(msg) {
     return msg.sender?.sender_id?.open_id

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-lark",
-  "version": "6.0.2",
+  "version": "6.0.3",
   "description": "Zhin.js Lark/Feishu (飞书) adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,21 +34,22 @@
     "directory": "plugins/adapters/lark"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/command": "1.0.6",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/host-http": "1.0.5",
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/command": "1.0.7",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/host-http": "1.0.6",
+    "@zhin.js/im-contract": "1.0.1",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/plugin-runtime": "1.1.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/agent": "1.1.2",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/host-http": "1.0.5",
-    "@zhin.js/plugin-runtime": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/agent": "1.1.3",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/host-http": "1.0.6",
+    "@zhin.js/plugin-runtime": "1.1.3",
+    "zhin.js": "6.0.2"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -66,8 +67,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/agent": "1.1.3",
+    "zhin.js": "6.0.2"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -3,7 +3,7 @@
  */
 import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
-import type { EndpointGroup, EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointGroup, EndpointInstance, EndpointManagement, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -18,9 +18,9 @@ import {
   formatInboundContent,
   formatOutboundBody,
   generateMessageId,
+  larkInboundConversation,
   resolveChatType,
   resolveSender,
-  resolveTarget,
   type AccessToken,
   type LarkApiResponse,
   type LarkMessage,
@@ -151,14 +151,14 @@ export class LarkEndpoint implements EndpointInstance {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  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: target,
+        receive_id: conversation.id,
         msg_type: content.msg_type,
         content: content.content,
       },
@@ -170,7 +170,7 @@ export class LarkEndpoint implements EndpointInstance {
     logger.debug(formatCompact({
       op: 'send',
       endpoint: this.#options.config.name,
-      to: target,
+      to: conversation.id,
       id: messageId,
     }));
     return messageId;
@@ -234,13 +234,12 @@ export class LarkEndpoint implements EndpointInstance {
   /** Test / internal: admit a parsed message when open (non-webhook path). */
   admit(msg: LarkMessage): void {
     if (!this.#open) return;
-    const target = resolveTarget(msg);
+    const conversation = larkInboundConversation(String(this.#options.id), msg);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: generateMessageId(msg) },
       content: formatInboundContent(msg),
       sender: resolveSender(msg),
-      id: generateMessageId(msg),
       metadata: Object.freeze({
         messageType: msg.message_type,
         chatType: resolveChatType(msg.chat_id, msg.chat_type),
@@ -249,7 +248,7 @@ export class LarkEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'lark_gateway_receive_failed',
-        target,
+        conversation: conversation.id,
         error: err instanceof Error ? err.message : String(err),
       }));
     });

package/src/index.ts

@@ -3,12 +3,12 @@ export {
   formatOutboundBody,
   generateMessageId,
   headerValue,
+  larkInboundConversation,
   normalizeWebhookPath,
   readTextBody,
   resolveChatType,
   resolveLarkConfig,
   resolveSender,
-  resolveTarget,
   verifySignature,
   type AccessToken,
   type LarkAdapterConfig,

package/src/protocol.ts

@@ -6,6 +6,7 @@
 import { createHash, timingSafeEqual } from 'node:crypto';
 import type { IncomingMessage } from 'node:http';
 import { isMediaRef } from '@zhin.js/core';
+import type { ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('lark');
@@ -158,8 +159,17 @@ export function resolveChatType(chatId?: string, chatType?: string): 'group' | '
   return chatId?.startsWith('oc_') ? 'group' : 'private';
 }
 
-export function resolveTarget(msg: LarkMessage): string {
-  return msg.chat_id || 'unknown';
+/**
+ * 入站归一化 → ConversationRef：`chat_type` 为 'group' 的会话映射为 group，
+ * p2p 单聊映射为 private；id 一律为平台 chat_id。Lark 无 guild/频道容器，
+ * 不产生 `parent`。
+ */
+export function larkInboundConversation(endpointId: string, msg: LarkMessage): ConversationRef {
+  return {
+    endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+    kind: resolveChatType(msg.chat_id, msg.chat_type),
+    id: msg.chat_id || 'unknown',
+  };
 }
 
 export function resolveSender(msg: LarkMessage): string {