@zhin.js/adapter-lark 7.0.0 → 7.0.2

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @zhin.js/adapter-lark
 
+## 7.0.2
+
+### Patch Changes
+
+- Updated dependencies [736fa04]
+  - @zhin.js/agent@1.1.17
+  - zhin.js@6.0.14
+
+## 7.0.1
+
+### Patch Changes
+
+- 1fc78bc: Unify native platform Client access behind the literal `adapter` discriminant. Handlers infer both native events and Clients, while command, inbound/outbound middleware, and both Agent tool authoring surfaces expose the exact operation-scoped Client through a lazy `$client` getter. Definitions without `adapter` keep `$client` typed as `unknown`, and runtime dispatch rejects adapter mismatches before resolving the Client. Bundled platform tools now use this single path instead of model-provided endpoint ids and adapter-specific dependency wrappers. Every adapter registers one Client/EventMap contract, and protocol adapters including NapCat, Milky, OneBot and Satori now produce transport-independent Client objects rather than letting Endpoint instances impersonate Clients.
+- Updated dependencies [e9c6a73]
+- Updated dependencies [4e8117c]
+- Updated dependencies [902fa35]
+- Updated dependencies [54bfd6b]
+- Updated dependencies [12025ee]
+- Updated dependencies [09b14d6]
+- Updated dependencies [1fc78bc]
+  - @zhin.js/agent@1.1.16
+  - @zhin.js/adapter@1.2.1
+  - @zhin.js/core@1.5.14
+  - @zhin.js/host-http@1.0.13
+  - @zhin.js/command@1.0.16
+  - @zhin.js/logger@1.0.77
+  - zhin.js@6.0.14
+  - @zhin.js/feature-kit@1.0.13
+  - @zhin.js/permission@1.0.4
+
 ## 7.0.0
 
 ### Patch Changes

package/README.md

@@ -20,7 +20,7 @@ pnpm add @zhin.js/adapter-lark
 ## Plugin Runtime
 
 - `@zhin.js/adapter` — 约定式 `adapters/lark.ts`（`defineAdapter`）
-- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
 - `@zhin.js/host-http` — `httpHostToken` 注册 Webhook 路由（**非** legacy host-router/Koa）
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
@@ -79,7 +79,7 @@ plugins:
 
 ## Agent 工具
 
-`agent/` 目录保留（get_user、群聊、管理员、上传文件等）。Endpoint 在 `start` 时自注册到 `lark-agent-deps`。
+`agent/` 目录保留（get_user、群聊、管理员、上传文件等）。工具声明 `adapter: 'lark'` 后，通过惰性的 `context.$client` 自动取得当前操作的 `LarkClient`；无需把 Endpoint id 暴露给模型。
 
 ## 平台权限（platform permit）
 
@@ -91,3 +91,12 @@ plugins:
 pnpm --filter @zhin.js/adapter-lark build
 pnpm --filter @zhin.js/adapter-lark test
 ```
+
+## 故障排查
+
+| 现象 | 排查 |
+| --- | --- |
+| URL 验证失败 | 检查公网 HTTPS、`webhookPath`、verification token 与 encrypt key |
+| Tenant Token 获取失败 | 检查 `appId`、`appSecret` 与应用版本是否已发布 |
+| 群里 @机器人不触发 AI | 当前无法可靠判定 bot open_id；使用显式 AI 前缀 |
+| 能收不能发 | 检查机器人消息权限、可见范围与应用是否已加入群聊 |

package/adapters/lark.js

@@ -3,7 +3,6 @@
  * Convention entry: discover `adapters/lark.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { LarkEndpoint } from "../lib/endpoint.js";
 import { resolveLarkConfig, } from "../lib/protocol.js";
@@ -30,8 +29,6 @@ export default defineAdapter({
         });
         return new LarkEndpoint({
             id: context.id,
-            gateway: context.use(messageGatewayToken),
-            sideEvents: context.use(sideEventGatewayToken),
             http: context.use(httpHostToken),
             config,
         });

package/adapters/lark.ts

@@ -2,7 +2,6 @@
  * Convention entry: discover `adapters/lark.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { LarkEndpoint } from '../src/endpoint.js';
 import {
@@ -35,8 +34,6 @@ export default defineAdapter<LarkAdapterConfig>({
     });
     return new LarkEndpoint({
       id: context.id,
-      gateway: context.use(messageGatewayToken),
-      sideEvents: context.use(sideEventGatewayToken),
       http: context.use(httpHostToken),
       config,
     });

package/agent/tools/add_members.ts

@@ -1,20 +1,18 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getLarkAgentDeps } from '../../src/lark-agent-deps.js';
 import { platformPermit } from '../../src/platform-permit.js';
 
-export default defineAgentTool<{ endpoint_id: string; chat_id: string; user_ids: string }>({
+export default defineAgentTool<{ chat_id: string; user_ids: string }>({
   description: '添加飞书群成员',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     chat_id: z.string().describe('群聊 ID'),
     user_ids: z.string().describe('用户 open_id 列表，逗号分隔'),
   }),
-  platforms: ['lark'],
+  adapter: 'lark',
   tags: ['lark'],
   permissions: [platformPermit('chat_admin')],
-  async execute({ endpoint_id, chat_id, user_ids   }: { endpoint_id: string; chat_id: string; user_ids: string }) {
-    const endpoint = getLarkAgentDeps().getEndpoint(endpoint_id);
+  async execute({ chat_id, user_ids   }: { chat_id: string; user_ids: string }, context) {
+    const endpoint = context.$client;
     const success = await endpoint.addChatMembers(chat_id, user_ids.split(','));
     return { success, message: success ? '成员添加成功' : '添加失败' };
   },

package/agent/tools/create_chat.ts

@@ -1,18 +1,16 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getLarkAgentDeps } from '../../src/lark-agent-deps.js';
-export default defineAgentTool<{ endpoint_id: string; name: string; members: string; owner?: string }>({
+export default defineAgentTool<{ name: string; members: string; owner?: string }>({
   description: '创建飞书群聊',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     name: z.string().describe('群名'),
     members: z.string().describe('成员 open_id 列表，逗号分隔'),
     owner: z.string().optional().describe('群主 open_id（可选）'),
   }),
-  platforms: ['lark'],
+  adapter: 'lark',
   tags: ['lark'],
-  async execute({ endpoint_id, name, members, owner   }: { endpoint_id: string; name: string; members: string; owner?: string }) {
-    const endpoint = getLarkAgentDeps().getEndpoint(endpoint_id);
+  async execute({ name, members, owner   }: { name: string; members: string; owner?: string }, context) {
+    const endpoint = context.$client;
     const chatId = await endpoint.createChat(name, members.split(','), owner);
     return { success: !!chatId, chat_id: chatId, message: chatId ? `群聊创建成功: ${chatId}` : '创建失败' };
   },

package/agent/tools/dissolve_chat.ts

@@ -1,16 +1,14 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getLarkAgentDeps } from '../../src/lark-agent-deps.js';
-export default defineAgentTool<{ endpoint_id: string; chat_id: string }>({
+export default defineAgentTool<{ chat_id: string }>({
   description: '解散飞书群聊（需要群主权限）',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     chat_id: z.string().describe('群聊 ID'),
   }),
-  platforms: ['lark'],
+  adapter: 'lark',
   tags: ['lark'],
-  async execute({ endpoint_id, chat_id   }: { endpoint_id: string; chat_id: string }) {
-    const endpoint = getLarkAgentDeps().getEndpoint(endpoint_id);
+  async execute({ chat_id   }: { chat_id: string }, context) {
+    const endpoint = context.$client;
     const success = await endpoint.dissolveChat(chat_id);
     return { success, message: success ? '群聊已解散' : '解散失败' };
   },

package/agent/tools/get_user.ts

@@ -1,17 +1,15 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getLarkAgentDeps } from '../../src/lark-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; user_id: string }>({
+export default defineAgentTool<{ user_id: string }>({
   description: '获取飞书用户信息',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     user_id: z.string().describe('用户 ID (open_id)'),
   }),
-  platforms: ['lark'],
+  adapter: 'lark',
   tags: ['lark'],
-  async execute({ endpoint_id, user_id   }: { endpoint_id: string; user_id: string }) {
-    const endpoint = getLarkAgentDeps().getEndpoint(endpoint_id);
+  async execute({ user_id   }: { user_id: string }, context) {
+    const endpoint = context.$client;
     return await endpoint.getUserInfo(user_id);
   },
 });

package/agent/tools/remove_managers.ts

@@ -1,20 +1,18 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getLarkAgentDeps } from '../../src/lark-agent-deps.js';
 import { platformPermit } from '../../src/platform-permit.js';
 
-export default defineAgentTool<{ endpoint_id: string; chat_id: string; user_ids: string }>({
+export default defineAgentTool<{ chat_id: string; user_ids: string }>({
   description: '移除飞书群管理员',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     chat_id: z.string().describe('群聊 ID'),
     user_ids: z.string().describe('用户 open_id 列表，逗号分隔'),
   }),
-  platforms: ['lark'],
+  adapter: 'lark',
   tags: ['lark'],
   permissions: [platformPermit('manage_managers')],
-  async execute({ endpoint_id, chat_id, user_ids   }: { endpoint_id: string; chat_id: string; user_ids: string }) {
-    const endpoint = getLarkAgentDeps().getEndpoint(endpoint_id);
+  async execute({ chat_id, user_ids   }: { chat_id: string; user_ids: string }, context) {
+    const endpoint = context.$client;
     const success = await endpoint.removeChatManagers(chat_id, user_ids.split(','));
     return { success, message: success ? '管理员移除成功' : '移除失败' };
   },

package/agent/tools/set_managers.ts

@@ -1,20 +1,18 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getLarkAgentDeps } from '../../src/lark-agent-deps.js';
 import { platformPermit } from '../../src/platform-permit.js';
 
-export default defineAgentTool<{ endpoint_id: string; chat_id: string; user_ids: string }>({
+export default defineAgentTool<{ chat_id: string; user_ids: string }>({
   description: '设置飞书群管理员',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     chat_id: z.string().describe('群聊 ID'),
     user_ids: z.string().describe('用户 open_id 列表，逗号分隔'),
   }),
-  platforms: ['lark'],
+  adapter: 'lark',
   tags: ['lark'],
   permissions: [platformPermit('manage_managers')],
-  async execute({ endpoint_id, chat_id, user_ids   }: { endpoint_id: string; chat_id: string; user_ids: string }) {
-    const endpoint = getLarkAgentDeps().getEndpoint(endpoint_id);
+  async execute({ chat_id, user_ids   }: { chat_id: string; user_ids: string }, context) {
+    const endpoint = context.$client;
     const success = await endpoint.setChatManagers(chat_id, user_ids.split(','));
     return { success, message: success ? '管理员设置成功' : '设置失败' };
   },

package/agent/tools/update_chat.ts

@@ -1,21 +1,19 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getLarkAgentDeps } from '../../src/lark-agent-deps.js';
 import { platformPermit } from '../../src/platform-permit.js';
 
-export default defineAgentTool<{ endpoint_id: string; chat_id: string; name?: string; description?: string }>({
+export default defineAgentTool<{ chat_id: string; name?: string; description?: string }>({
   description: '更新飞书群聊信息（群名、描述）',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     chat_id: z.string().describe('群聊 ID'),
     name: z.string().optional().describe('新群名（可选）'),
     description: z.string().optional().describe('新描述（可选）'),
   }),
-  platforms: ['lark'],
+  adapter: 'lark',
   tags: ['lark'],
   permissions: [platformPermit('chat_admin')],
-  async execute({ endpoint_id, chat_id, name, description   }: { endpoint_id: string; chat_id: string; name?: string; description?: string }) {
-    const endpoint = getLarkAgentDeps().getEndpoint(endpoint_id);
+  async execute({ chat_id, name, description   }: { chat_id: string; name?: string; description?: string }, context) {
+    const endpoint = context.$client;
     const success = await endpoint.updateChatInfo(chat_id, { name, description });
     return { success, message: success ? '群信息更新成功' : '更新失败' };
   },

package/agent/tools/upload_file.ts

@@ -1,26 +1,22 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getLarkAgentDeps } from '../../src/lark-agent-deps.js';
 
 export default defineAgentTool<{
-  endpoint_id: string;
   file_path: string;
   file_type: 'image' | 'file' | 'video' | 'audio';
 }>({
   description: '上传文件到飞书（image/file/video/audio）',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     file_path: z.string().describe('本地文件路径'),
     file_type: z.enum(['image', 'file', 'video', 'audio']).default('file').describe('飞书文件类型'),
   }),
-  platforms: ['lark'],
+  adapter: 'lark',
   tags: ['lark'],
-  async execute({ endpoint_id, file_path, file_type }: {
-    endpoint_id: string;
+  async execute({ file_path, file_type }: {
     file_path: string;
     file_type: 'image' | 'file' | 'video' | 'audio';
-  }) {
-    const endpoint = getLarkAgentDeps().getEndpoint(endpoint_id);
+  }, context) {
+    const endpoint = context.$client;
     const result = await endpoint.uploadFile(file_path, file_type);
     return { success: true, file_key: result, message: `文件已上传，file_key: ${result}` };
   },

package/lib/client.d.ts

@@ -0,0 +1,12 @@
+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 declare const larkClient: import("@zhin.js/adapter").EndpointClientToken<LarkClient, LarkClientEventMap>;

package/lib/client.js

@@ -0,0 +1,2 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+export const larkClient = defineEndpointClient('lark');

package/lib/endpoint.d.ts

@@ -1,5 +1,5 @@
-import { type EndpointControl, type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import { Endpoint } from 'zhin.js/adapter';
+import { type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { resolveMediaBinary } from './media-upload.js';
@@ -17,14 +17,48 @@ export type LarkFetch = (url: string, init?: {
 }>;
 export interface LarkEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: ResolvedLarkConfig;
     readonly fetch?: LarkFetch;
 }
-export declare class LarkEndpoint implements EndpointInstance {
+export interface LarkClientApi {
+    getUserInfo(userId: string, userIdType?: 'open_id' | 'user_id' | 'union_id'): Promise<unknown>;
+    getChatInfo(chatId: string): Promise<unknown>;
+    uploadFile(filePath: string, fileType?: 'image' | 'file' | 'video' | 'audio'): Promise<string | null>;
+    createChat(name: string, userIds: string[], ownerId?: string): Promise<string | null>;
+    updateChatInfo(chatId: string, options: {
+        name?: string;
+        description?: string;
+    }): Promise<boolean>;
+    addChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
+    removeChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
+    getChatMembers(chatId: string): Promise<unknown[]>;
+    dissolveChat(chatId: string): Promise<boolean>;
+    setChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
+    removeChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
+}
+/** Feishu/Lark OpenAPI client surface carried by every Endpoint event. */
+export declare class LarkClient implements LarkClientApi {
+    readonly api: LarkClientApi;
+    constructor(api: LarkClientApi);
+    getUserInfo: (id: string, type?: "open_id" | "user_id" | "union_id") => Promise<unknown>;
+    getChatInfo: (id: string) => Promise<unknown>;
+    uploadFile: (path: string, type?: "image" | "file" | "video" | "audio") => Promise<string | null>;
+    createChat: (name: string, users: string[], owner?: string) => Promise<string | null>;
+    updateChatInfo: (id: string, options: {
+        name?: string;
+        description?: string;
+    }) => Promise<boolean>;
+    addChatMembers: (id: string, users: string[]) => Promise<boolean>;
+    removeChatMembers: (id: string, users: string[]) => Promise<boolean>;
+    getChatMembers: (id: string) => Promise<unknown[]>;
+    dissolveChat: (id: string) => Promise<boolean>;
+    setChatManagers: (id: string, users: string[]) => Promise<boolean>;
+    removeChatManagers: (id: string, users: string[]) => Promise<boolean>;
+}
+export declare class LarkEndpoint extends Endpoint<LarkClient> {
     #private;
+    readonly client: LarkClient;
     /**
      * Console 社交面语义端口。Lark OpenAPI 仅接读取类列表能力：
      * - listGroups：GET /im/v1/chats（bot 所在群列表，分页归一为 {group_id: chat_id, name}）
@@ -48,6 +82,7 @@ export declare class LarkEndpoint implements EndpointInstance {
     uploadImage(media: Parameters<typeof resolveMediaBinary>[0]): Promise<string | null>;
     /** Test / internal: admit a parsed message when open (non-webhook path). */
     admit(msg: LarkMessage): void;
+    admitPlatform(name: string, event: unknown): void;
     getUserInfo(userId: string, userIdType?: 'open_id' | 'user_id' | 'union_id'): Promise<unknown>;
     getChatInfo(chatId: string): Promise<unknown>;
     uploadFile(filePath: string, fileType?: 'image' | 'file' | 'video' | 'audio'): Promise<string | null>;

package/lib/endpoint.js

@@ -1,3 +1,4 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
  * LarkEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
  */
@@ -5,13 +6,43 @@ import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
 import { createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
-import { registerLarkAgentEndpoint } from './lark-agent-deps.js';
 import { buildImageUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
 import { formatInboundContent, formatOutboundBody, generateMessageId, larkInboundConversation, resolveChatType, resolveSender, } from './protocol.js';
 import { registerLarkWebhookRoutes } from './webhook.js';
 /** 出站 HTTP 调用统一 30s 超时。 */
 const OUTBOUND_TIMEOUT_MS = 30_000;
-export class LarkEndpoint {
+/** Feishu/Lark OpenAPI client surface carried by every Endpoint event. */
+export class LarkClient {
+    api;
+    constructor(api) {
+        this.api = api;
+    }
+    getUserInfo = (id, type) => this.api.getUserInfo(id, type);
+    getChatInfo = (id) => this.api.getChatInfo(id);
+    uploadFile = (path, type) => this.api.uploadFile(path, type);
+    createChat = (name, users, owner) => this.api.createChat(name, users, owner);
+    updateChatInfo = (id, options) => this.api.updateChatInfo(id, options);
+    addChatMembers = (id, users) => this.api.addChatMembers(id, users);
+    removeChatMembers = (id, users) => this.api.removeChatMembers(id, users);
+    getChatMembers = (id) => this.api.getChatMembers(id);
+    dissolveChat = (id) => this.api.dissolveChat(id);
+    setChatManagers = (id, users) => this.api.setChatManagers(id, users);
+    removeChatManagers = (id, users) => this.api.removeChatManagers(id, users);
+}
+export class LarkEndpoint extends Endpoint {
+    client = new LarkClient({
+        getUserInfo: (id, type) => this.getUserInfo(id, type),
+        getChatInfo: (id) => this.getChatInfo(id),
+        uploadFile: (path, type) => this.uploadFile(path, type),
+        createChat: (name, users, owner) => this.createChat(name, users, owner),
+        updateChatInfo: (id, options) => this.updateChatInfo(id, options),
+        addChatMembers: (id, users) => this.addChatMembers(id, users),
+        removeChatMembers: (id, users) => this.removeChatMembers(id, users),
+        getChatMembers: (id) => this.getChatMembers(id),
+        dissolveChat: (id) => this.dissolveChat(id),
+        setChatManagers: (id, users) => this.setChatManagers(id, users),
+        removeChatManagers: (id, users) => this.removeChatManagers(id, users),
+    });
     #logger;
     #options;
     #fetch;
@@ -45,8 +76,8 @@ export class LarkEndpoint {
     #refreshPromise = null;
     #open = false;
     #started = false;
-    #unregisterAgent;
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('lark', options.config.id);
         this.#options = options;
         this.#fetch = options.fetch ?? globalThis.fetch;
@@ -73,7 +104,6 @@ export class LarkEndpoint {
                 }));
             }
             await this.#refreshAccessToken();
-            this.#unregisterAgent = registerLarkAgentEndpoint(this.#options.config.id, this);
             this.#routeReleases.push(...registerLarkWebhookRoutes(this.#options.http, this));
             this.#logger.debug(formatCompact({
                 endpoint: this.#options.config.id,
@@ -97,8 +127,6 @@ export class LarkEndpoint {
         this.#open = false;
         for (const release of this.#routeReleases.splice(0))
             release();
-        this.#unregisterAgent?.();
-        this.#unregisterAgent = undefined;
         this.#started = false;
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
@@ -186,7 +214,7 @@ export class LarkEndpoint {
         if (!this.#open)
             return;
         const conversation = larkInboundConversation(String(this.#options.id), msg);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: generateMessageId(msg) },
             content: formatInboundContent(msg),
@@ -204,6 +232,17 @@ export class LarkEndpoint {
             }));
         });
     }
+    admitPlatform(name, event) {
+        if (!this.#open)
+            return;
+        void this.emitPlatform(name, event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'lark_platform_event_failed',
+                event: name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    }
     async getUserInfo(userId, userIdType = 'open_id') {
         try {
             const data = await this.#request(`/contact/v3/users/${userId}`, {

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 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 { larkClient, type LarkClientEventMap } from './client.js';
 export { checkLarkPlatformPermit, larkGroupPermitResolver, normalizeLarkSenderForPermit, platformPermit, } from './platform-permit.js';
-export { LarkEndpoint, type LarkEndpointOptions, type LarkFetch, } from './endpoint.js';
+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';

package/lib/index.js

@@ -1,6 +1,6 @@
 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 { larkClient } from './client.js';
 export { checkLarkPlatformPermit, larkGroupPermitResolver, normalizeLarkSenderForPermit, platformPermit, } from './platform-permit.js';
-export { LarkEndpoint, } from './endpoint.js';
+export { LarkClient, LarkEndpoint, } from './endpoint.js';
 export { buildImageUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
 export { registerLarkWebhookRoutes, handleLarkWebhookRequest, } from './webhook.js';

package/lib/lark-endpoint-commands.d.ts

@@ -1 +1 @@
-export declare const larkEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;
+export declare const larkEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;

package/lib/protocol.d.ts

@@ -105,7 +105,7 @@ export declare function resolveChatType(chatId?: string, chatType?: string): 'gr
 export declare function larkInboundConversation(endpointKey: string, msg: LarkMessage): ConversationRef;
 export declare function resolveSender(msg: LarkMessage): string;
 export declare function generateMessageId(msg: LarkMessage): string;
-/** Build inbound text for MessageGateway.receive. */
+/** Build inbound text for OutboundMessageService.receive. */
 export declare function formatInboundContent(msg: LarkMessage): string;
 /** 验签时间戳时效窗口（防重放）。 */
 export declare const LARK_SIGNATURE_MAX_AGE_MS: number;

package/lib/protocol.js

@@ -69,7 +69,7 @@ export function resolveSender(msg) {
 export function generateMessageId(msg) {
     return msg.message_id || `${msg.create_time ?? Date.now()}`;
 }
-/** Build inbound text for MessageGateway.receive. */
+/** Build inbound text for OutboundMessageService.receive. */
 export function formatInboundContent(msg) {
     if (!msg.content || !msg.message_type)
         return '';

package/lib/webhook.d.ts

@@ -7,6 +7,7 @@ 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[];

package/lib/webhook.js

@@ -44,6 +44,12 @@ export async function handleLarkWebhookRequest(request, response, handler) {
             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 }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-lark",
-  "version": "7.0.0",
+  "version": "7.0.2",
   "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.2.0",
-    "@zhin.js/core": "1.5.13",
-    "@zhin.js/host-http": "1.0.12",
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/core": "1.5.14",
+    "@zhin.js/feature-kit": "1.0.13",
+    "@zhin.js/host-http": "1.0.13",
     "@zhin.js/im-contract": "1.0.4",
-    "@zhin.js/logger": "1.0.76"
+    "@zhin.js/logger": "1.0.77"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.2.0",
-    "@zhin.js/agent": "1.1.15",
-    "@zhin.js/command": "1.0.15",
-    "@zhin.js/core": "1.5.13",
-    "@zhin.js/host-http": "1.0.12",
-    "@zhin.js/permission": "1.0.3",
-    "zhin.js": "6.0.13"
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/agent": "1.1.17",
+    "@zhin.js/command": "1.0.16",
+    "@zhin.js/core": "1.5.14",
+    "@zhin.js/host-http": "1.0.13",
+    "@zhin.js/permission": "1.0.4",
+    "zhin.js": "6.0.14"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -69,8 +70,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.15",
-    "zhin.js": "6.0.13"
+    "@zhin.js/agent": "1.1.17",
+    "zhin.js": "6.0.14"
   },
   "files": [
     "adapters",

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');

package/src/endpoint.ts

@@ -1,3 +1,4 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
  * LarkEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
  */
@@ -7,15 +8,12 @@ import {
   createRecallEndpointControl,
   type EndpointControl,
   type EndpointGroup,
-  type EndpointInstance,
   type EndpointManagement,
   type EndpointSendRequest,
 } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
-import { registerLarkAgentEndpoint } from './lark-agent-deps.js';
 import {
   buildImageUploadForm,
   readOutboundImageMedia,
@@ -55,14 +53,59 @@ export type LarkFetch = (
 
 export interface LarkEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: ResolvedLarkConfig;
   readonly fetch?: LarkFetch;
 }
 
-export class LarkEndpoint implements EndpointInstance {
+export interface LarkClientApi {
+  getUserInfo(userId: string, userIdType?: 'open_id' | 'user_id' | 'union_id'): Promise<unknown>;
+  getChatInfo(chatId: string): Promise<unknown>;
+  uploadFile(filePath: string, fileType?: 'image' | 'file' | 'video' | 'audio'): Promise<string | null>;
+  createChat(name: string, userIds: string[], ownerId?: string): Promise<string | null>;
+  updateChatInfo(chatId: string, options: { name?: string; description?: string }): Promise<boolean>;
+  addChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
+  removeChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
+  getChatMembers(chatId: string): Promise<unknown[]>;
+  dissolveChat(chatId: string): Promise<boolean>;
+  setChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
+  removeChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
+}
+
+/** Feishu/Lark OpenAPI client surface carried by every Endpoint event. */
+export class LarkClient implements LarkClientApi {
+  constructor(readonly api: LarkClientApi) {}
+  getUserInfo = (id: string, type?: 'open_id' | 'user_id' | 'union_id') =>
+    this.api.getUserInfo(id, type);
+  getChatInfo = (id: string) => this.api.getChatInfo(id);
+  uploadFile = (path: string, type?: 'image' | 'file' | 'video' | 'audio') =>
+    this.api.uploadFile(path, type);
+  createChat = (name: string, users: string[], owner?: string) =>
+    this.api.createChat(name, users, owner);
+  updateChatInfo = (id: string, options: { name?: string; description?: string }) =>
+    this.api.updateChatInfo(id, options);
+  addChatMembers = (id: string, users: string[]) => this.api.addChatMembers(id, users);
+  removeChatMembers = (id: string, users: string[]) => this.api.removeChatMembers(id, users);
+  getChatMembers = (id: string) => this.api.getChatMembers(id);
+  dissolveChat = (id: string) => this.api.dissolveChat(id);
+  setChatManagers = (id: string, users: string[]) => this.api.setChatManagers(id, users);
+  removeChatManagers = (id: string, users: string[]) => this.api.removeChatManagers(id, users);
+}
+
+export class LarkEndpoint extends Endpoint<LarkClient> {
+  readonly client = new LarkClient({
+    getUserInfo: (id, type) => this.getUserInfo(id, type),
+    getChatInfo: (id) => this.getChatInfo(id),
+    uploadFile: (path, type) => this.uploadFile(path, type),
+    createChat: (name, users, owner) => this.createChat(name, users, owner),
+    updateChatInfo: (id, options) => this.updateChatInfo(id, options),
+    addChatMembers: (id, users) => this.addChatMembers(id, users),
+    removeChatMembers: (id, users) => this.removeChatMembers(id, users),
+    getChatMembers: (id) => this.getChatMembers(id),
+    dissolveChat: (id) => this.dissolveChat(id),
+    setChatManagers: (id, users) => this.setChatManagers(id, users),
+    removeChatManagers: (id, users) => this.removeChatManagers(id, users),
+  });
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: LarkEndpointOptions;
@@ -99,9 +142,9 @@ export class LarkEndpoint implements EndpointInstance {
   #refreshPromise: Promise<string> | null = null;
   #open = false;
   #started = false;
-  #unregisterAgent?: () => void;
 
   constructor(options: LarkEndpointOptions) {
+    super();
     this.#logger = getAdapterLogger('lark', options.config.id);
     this.#options = options;
     this.#fetch = options.fetch ?? globalThis.fetch;
@@ -130,7 +173,6 @@ export class LarkEndpoint implements EndpointInstance {
         }));
       }
       await this.#refreshAccessToken();
-      this.#unregisterAgent = registerLarkAgentEndpoint(this.#options.config.id, this);
       this.#routeReleases.push(...registerLarkWebhookRoutes(this.#options.http, this));
       this.#logger.debug(formatCompact({
         endpoint: this.#options.config.id,
@@ -155,8 +197,6 @@ export class LarkEndpoint implements EndpointInstance {
   async stop(): Promise<void> {
     this.#open = false;
     for (const release of this.#routeReleases.splice(0)) release();
-    this.#unregisterAgent?.();
-    this.#unregisterAgent = undefined;
     this.#started = false;
     this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
@@ -242,7 +282,7 @@ export class LarkEndpoint implements EndpointInstance {
   admit(msg: LarkMessage): void {
     if (!this.#open) return;
     const conversation = larkInboundConversation(String(this.#options.id), msg);
-    void this.#options.gateway.receive({
+    void this.emit('message.receive', {
       conversation,
       message: { conversation, id: generateMessageId(msg) },
       content: formatInboundContent(msg),
@@ -261,6 +301,17 @@ export class LarkEndpoint implements EndpointInstance {
     });
   }
 
+  admitPlatform(name: string, event: unknown): void {
+    if (!this.#open) return;
+    void this.emitPlatform(name, event).catch((error) => {
+      this.#logger.warn(formatCompact({
+        op: 'lark_platform_event_failed',
+        event: name,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    });
+  }
+
   async getUserInfo(
     userId: string,
     userIdType: 'open_id' | 'user_id' | 'union_id' = 'open_id',

package/src/index.ts

@@ -20,13 +20,7 @@ export {
   type ResolvedLarkConfig,
 } from './protocol.js';
 
-export {
-  getLarkAgentDeps,
-  registerLarkAgentEndpoint,
-  setLarkAgentDeps,
-  type LarkAgentDeps,
-  type LarkAgentEndpoint,
-} from './lark-agent-deps.js';
+export { larkClient, type LarkClientEventMap } from './client.js';
 
 export {
   checkLarkPlatformPermit,
@@ -36,7 +30,9 @@ export {
 } from './platform-permit.js';
 
 export {
+  LarkClient,
   LarkEndpoint,
+  type LarkClientApi,
   type LarkEndpointOptions,
   type LarkFetch,
 } from './endpoint.js';

package/src/protocol.ts

@@ -182,7 +182,7 @@ export function generateMessageId(msg: LarkMessage): string {
   return msg.message_id || `${msg.create_time ?? Date.now()}`;
 }
 
-/** Build inbound text for MessageGateway.receive. */
+/** Build inbound text for OutboundMessageService.receive. */
 export function formatInboundContent(msg: LarkMessage): string {
   if (!msg.content || !msg.message_type) return '';
   try {

package/src/webhook.ts

@@ -19,6 +19,7 @@ const logger = getLogger('lark');
 export interface LarkWebhookHandler {
   readonly config: ResolvedLarkConfig;
   readonly isOpen: boolean;
+  admitPlatform(name: string, event: unknown): void;
   admit(msg: LarkMessage): void;
 }
 
@@ -78,6 +79,13 @@ export async function handleLarkWebhookRequest(
       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 }));

package/lib/lark-agent-deps.d.ts

@@ -1,27 +0,0 @@
-/**
- * Agent tool deps for lark (user / chat / managers / upload).
- * Endpoints register themselves on start; tools look up by endpoint id.
- */
-export interface LarkAgentEndpoint {
-    getUserInfo(userId: string, userIdType?: 'open_id' | 'user_id' | 'union_id'): Promise<unknown>;
-    getChatInfo(chatId: string): Promise<unknown>;
-    uploadFile(filePath: string, fileType?: 'image' | 'file' | 'video' | 'audio'): Promise<string | null>;
-    createChat(name: string, userIds: string[], ownerId?: string): Promise<string | null>;
-    updateChatInfo(chatId: string, options: {
-        name?: string;
-        description?: string;
-    }): Promise<boolean>;
-    addChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
-    removeChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
-    getChatMembers(chatId: string): Promise<unknown[]>;
-    dissolveChat(chatId: string): Promise<boolean>;
-    setChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
-    removeChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
-}
-export interface LarkAgentDeps {
-    getEndpoint: (endpointKey: string) => LarkAgentEndpoint;
-}
-export declare function registerLarkAgentEndpoint(endpointKey: string, endpoint: LarkAgentEndpoint): () => void;
-/** Optional override used by tests / transitional callers. Pass `null` to clear. */
-export declare function setLarkAgentDeps(deps: LarkAgentDeps | null): void;
-export declare function getLarkAgentDeps(): LarkAgentDeps;

package/lib/lark-agent-deps.js

@@ -1,30 +0,0 @@
-/**
- * Agent tool deps for lark (user / chat / managers / upload).
- * Endpoints register themselves on start; tools look up by endpoint id.
- */
-const endpoints = new Map();
-let override = null;
-export function registerLarkAgentEndpoint(endpointKey, endpoint) {
-    endpoints.set(endpointKey, endpoint);
-    return () => {
-        if (endpoints.get(endpointKey) === endpoint) {
-            endpoints.delete(endpointKey);
-        }
-    };
-}
-/** Optional override used by tests / transitional callers. Pass `null` to clear. */
-export function setLarkAgentDeps(deps) {
-    override = deps;
-}
-export function getLarkAgentDeps() {
-    if (override)
-        return override;
-    return {
-        getEndpoint(endpointKey) {
-            const endpoint = endpoints.get(endpointKey);
-            if (!endpoint)
-                throw new Error(`Endpoint ${endpointKey} 不存在`);
-            return endpoint;
-        },
-    };
-}

package/src/lark-agent-deps.ts

@@ -1,62 +0,0 @@
-/**
- * Agent tool deps for lark (user / chat / managers / upload).
- * Endpoints register themselves on start; tools look up by endpoint id.
- */
-
-export interface LarkAgentEndpoint {
-  getUserInfo(
-    userId: string,
-    userIdType?: 'open_id' | 'user_id' | 'union_id',
-  ): Promise<unknown>;
-  getChatInfo(chatId: string): Promise<unknown>;
-  uploadFile(
-    filePath: string,
-    fileType?: 'image' | 'file' | 'video' | 'audio',
-  ): Promise<string | null>;
-  createChat(name: string, userIds: string[], ownerId?: string): Promise<string | null>;
-  updateChatInfo(
-    chatId: string,
-    options: { name?: string; description?: string },
-  ): Promise<boolean>;
-  addChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
-  removeChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
-  getChatMembers(chatId: string): Promise<unknown[]>;
-  dissolveChat(chatId: string): Promise<boolean>;
-  setChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
-  removeChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
-}
-
-export interface LarkAgentDeps {
-  getEndpoint: (endpointKey: string) => LarkAgentEndpoint;
-}
-
-const endpoints = new Map<string, LarkAgentEndpoint>();
-let override: LarkAgentDeps | null = null;
-
-export function registerLarkAgentEndpoint(
-  endpointKey: string,
-  endpoint: LarkAgentEndpoint,
-): () => void {
-  endpoints.set(endpointKey, endpoint);
-  return () => {
-    if (endpoints.get(endpointKey) === endpoint) {
-      endpoints.delete(endpointKey);
-    }
-  };
-}
-
-/** Optional override used by tests / transitional callers. Pass `null` to clear. */
-export function setLarkAgentDeps(deps: LarkAgentDeps | null): void {
-  override = deps;
-}
-
-export function getLarkAgentDeps(): LarkAgentDeps {
-  if (override) return override;
-  return {
-    getEndpoint(endpointKey) {
-      const endpoint = endpoints.get(endpointKey);
-      if (!endpoint) throw new Error(`Endpoint ${endpointKey} 不存在`);
-      return endpoint;
-    },
-  };
-}