@zhin.js/adapter-wecom 4.0.14 → 5.0.1

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @zhin.js/adapter-wecom
 
+## 5.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
+
+## 5.0.0
+
+### Patch Changes
+
+- f2c532f: Expose exact per-Endpoint message operations through one validated Adapter capability model, route Core control calls through declared active capabilities, and connect existing recall, edit, reaction, and typing implementations across platform adapters.
+- Updated dependencies [b10d058]
+- Updated dependencies [f2c532f]
+- Updated dependencies [3dbf990]
+  - @zhin.js/host-http@1.0.12
+  - @zhin.js/adapter@1.2.0
+  - @zhin.js/core@1.5.13
+  - @zhin.js/agent@1.1.15
+  - zhin.js@6.0.13
+
 ## 4.0.14
 
 ### Patch Changes

package/README.md

@@ -18,7 +18,7 @@ pnpm add @zhin.js/adapter-wecom
 ## Plugin Runtime
 
 - `@zhin.js/adapter` — 约定式 `adapters/wecom.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>`

package/adapters/wecom.js

@@ -4,7 +4,6 @@
  * Implementation lives under `src/` (endpoint / webhook / protocol).
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { WecomEndpoint } from "../lib/endpoint.js";
 import { resolveWecomConfig, } from "../lib/protocol.js";
@@ -12,6 +11,7 @@ import { wecomRuntimeStateToken } from "../lib/wecom-runtime-state.js";
 export { WecomEndpoint } from "../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
     // image 段全部经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传、
     // base64/path 直接上传、file 引用直用 media_id）；无卡片交互面，交互段降级纯文本。
     segments: {
@@ -27,8 +27,6 @@ export default defineAdapter({
         });
         return new WecomEndpoint({
             id: context.id,
-            gateway: context.use(messageGatewayToken),
-            sideEvents: context.use(sideEventGatewayToken),
             http: context.use(httpHostToken),
             config,
         });

package/adapters/wecom.ts

@@ -3,7 +3,6 @@
  * Implementation lives under `src/` (endpoint / webhook / protocol).
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { WecomEndpoint } from '../src/endpoint.js';
 import {
@@ -17,6 +16,7 @@ export type { WecomEndpointOptions, WecomFetch } from '../src/endpoint.js';
 
 export default defineAdapter<WecomAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  operations: ['recall'],
   // image 段全部经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传、
   // base64/path 直接上传、file 引用直用 media_id）；无卡片交互面，交互段降级纯文本。
   segments: {
@@ -32,8 +32,6 @@ export default defineAdapter<WecomAdapterConfig>({
     });
     return new WecomEndpoint({
       id: context.id,
-      gateway: context.use(messageGatewayToken),
-      sideEvents: context.use(sideEventGatewayToken),
       http: context.use(httpHostToken),
       config,
     });

package/agent/tools/get_dept_users.ts

@@ -1,16 +1,14 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getWecomAgentDeps } from '../../src/wecom-agent-deps.js';
-export default defineAgentTool<{ endpoint_id: string; dept_id: string }>({
+export default defineAgentTool<{ dept_id: string }>({
   description: '获取企业微信部门用户列表',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     dept_id: z.string().describe('部门 ID'),
   }),
-  platforms: ['wecom'],
+  adapter: 'wecom',
   tags: ['wecom'],
-  async execute({ endpoint_id, dept_id    }: { endpoint_id: string; dept_id: string }) {
-    const endpoint = getWecomAgentDeps().getEndpoint(endpoint_id);
+  async execute({ dept_id    }: { dept_id: string }, context) {
+    const endpoint = context.$client;
     const users = await endpoint.getDepartmentUsers(Number(dept_id));
     return { users, count: users.length };
   },

package/agent/tools/get_user.ts

@@ -1,16 +1,14 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getWecomAgentDeps } from '../../src/wecom-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'),
   }),
-  platforms: ['wecom'],
+  adapter: 'wecom',
   tags: ['wecom'],
-  async execute({ endpoint_id, user_id    }: { endpoint_id: string; user_id: string }) {
-    const endpoint = getWecomAgentDeps().getEndpoint(endpoint_id);
+  async execute({ user_id    }: { user_id: string }, context) {
+    const endpoint = context.$client;
     return await endpoint.getUserInfo(user_id);
   },
 });

package/agent/tools/list_departments.ts

@@ -1,16 +1,14 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getWecomAgentDeps } from '../../src/wecom-agent-deps.js';
-export default defineAgentTool<{ endpoint_id: string; dept_id?: string }>({
+export default defineAgentTool<{ dept_id?: string }>({
   description: '获取企业微信部门列表',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     dept_id: z.string().optional().describe('父部门 ID，默认 1（根部门）'),
   }),
-  platforms: ['wecom'],
+  adapter: 'wecom',
   tags: ['wecom'],
-  async execute({ endpoint_id, dept_id    }: { endpoint_id: string; dept_id?: string }) {
-    const endpoint = getWecomAgentDeps().getEndpoint(endpoint_id);
+  async execute({ dept_id    }: { dept_id?: string }, context) {
+    const endpoint = context.$client;
     const departments = await endpoint.getDepartmentList(Number(dept_id) || 1);
     return { departments, count: departments.length };
   },

package/agent/tools/send_text.ts

@@ -1,17 +1,15 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getWecomAgentDeps } from '../../src/wecom-agent-deps.js';
-export default defineAgentTool<{ endpoint_id: string; user_id: string; content: string }>({
+export default defineAgentTool<{ user_id: string; content: string }>({
   description: '向指定企业微信用户发送文本消息',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     user_id: z.string().describe('用户 ID'),
     content: z.string().describe('消息内容'),
   }),
-  platforms: ['wecom'],
+  adapter: 'wecom',
   tags: ['wecom'],
-  async execute({ endpoint_id, user_id, content    }: { endpoint_id: string; user_id: string; content: string }) {
-    const endpoint = getWecomAgentDeps().getEndpoint(endpoint_id);
+  async execute({ user_id, content    }: { user_id: string; content: string }, context) {
+    const endpoint = context.$client;
     const success = await endpoint.sendTextMessage(user_id, content);
     return { success, message: success ? '消息已发送' : '发送失败' };
   },

package/lib/client.d.ts

@@ -0,0 +1,12 @@
+import type { WecomClient } from './endpoint.js';
+import type { WecomMessage } from './protocol.js';
+export type WecomClientEventMap = Record<string, WecomMessage>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly wecom: {
+            readonly client: WecomClient;
+            readonly events: WecomClientEventMap;
+        };
+    }
+}
+export declare const wecomClient: import("@zhin.js/adapter").EndpointClientToken<WecomClient, WecomClientEventMap>;

package/lib/client.js

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

package/lib/endpoint.d.ts

@@ -1,11 +1,11 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
  * WecomEndpoint — lifecycle, outbound send, inbound admit, OpenAPI helpers for agent tools.
  */
-import type { EndpointInstance, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import { type EndpointControl, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
-import { type ResolvedWecomConfig, type WecomApiResponse, type WecomMessage } from './protocol.js';
+import { type ResolvedWecomConfig, type WecomMessage } from './protocol.js';
 export type WecomFetch = (url: string, init?: {
     readonly method?: string;
     readonly headers?: Record<string, string>;
@@ -18,19 +18,34 @@ export type WecomFetch = (url: string, init?: {
 }>;
 export interface WecomEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: ResolvedWecomConfig;
     readonly fetch?: WecomFetch;
 }
+export interface WecomClientApi {
+    getUserInfo(userId: string): Promise<unknown>;
+    getDepartmentUsers(deptId: number): Promise<unknown[]>;
+    getDepartmentList(deptId?: number): Promise<unknown[]>;
+    sendTextMessage(userId: string, content: string): Promise<boolean>;
+}
+/** WeCom API surface exposed to plugin events without Endpoint lifecycle methods. */
+export declare class WecomClient implements WecomClientApi {
+    readonly api: WecomClientApi;
+    constructor(api: WecomClientApi);
+    getUserInfo: (userId: string) => Promise<unknown>;
+    getDepartmentUsers: (deptId: number) => Promise<unknown[]>;
+    getDepartmentList: (deptId?: number) => Promise<unknown[]>;
+    sendTextMessage: (userId: string, content: string) => Promise<boolean>;
+}
 /**
  * 企业微信服务端 API 无 bot 群列表/群成员列表接口（客户群接口属「客户联系」
  * 独立授权域，非 bot 社交面），好友/频道概念亦不存在；
  * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
  */
-export declare class WecomEndpoint implements EndpointInstance {
+export declare class WecomEndpoint extends Endpoint<WecomClient> {
     #private;
+    readonly client: WecomClient;
+    readonly control: EndpointControl;
     constructor(options: WecomEndpointOptions);
     /** Used by webhook handler. */
     get isOpen(): boolean;
@@ -43,8 +58,4 @@ export declare class WecomEndpoint implements EndpointInstance {
     recallMessage(messageId: string): Promise<void>;
     /** Test / internal: admit a parsed message when open (non-webhook path). */
     admit(msg: WecomMessage): void;
-    getUserInfo(userId: string): Promise<WecomApiResponse | null>;
-    getDepartmentUsers(deptId: number): Promise<unknown[]>;
-    getDepartmentList(deptId?: number): Promise<unknown[]>;
-    sendTextMessage(userId: string, content: string): Promise<boolean>;
 }

package/lib/endpoint.js

@@ -1,25 +1,47 @@
+import { Endpoint } from 'zhin.js/adapter';
+/**
+ * WecomEndpoint — lifecycle, outbound send, inbound admit, OpenAPI helpers for agent tools.
+ */
+import { createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
-import { registerWecomAgentEndpoint } from './wecom-agent-deps.js';
 import { buildMediaUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
 import { buildSendRequestBody, formatInboundContent, formatOutboundBody, resolveChatType, wecomInboundConversation, } from './protocol.js';
 import { registerWecomWebhookRoutes } from './webhook.js';
 import { receiveWecomSideEvent } from './side-event-dispatch.js';
+/** WeCom API surface exposed to plugin events without Endpoint lifecycle methods. */
+export class WecomClient {
+    api;
+    constructor(api) {
+        this.api = api;
+    }
+    getUserInfo = (userId) => this.api.getUserInfo(userId);
+    getDepartmentUsers = (deptId) => this.api.getDepartmentUsers(deptId);
+    getDepartmentList = (deptId) => this.api.getDepartmentList(deptId);
+    sendTextMessage = (userId, content) => this.api.sendTextMessage(userId, content);
+}
 /**
  * 企业微信服务端 API 无 bot 群列表/群成员列表接口（客户群接口属「客户联系」
  * 独立授权域，非 bot 社交面），好友/频道概念亦不存在；
  * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
  */
-export class WecomEndpoint {
+export class WecomEndpoint extends Endpoint {
+    client = new WecomClient({
+        getUserInfo: (userId) => this.#getUserInfo(userId),
+        getDepartmentUsers: (deptId) => this.#getDepartmentUsers(deptId),
+        getDepartmentList: (deptId) => this.#getDepartmentList(deptId),
+        sendTextMessage: (userId, content) => this.#sendTextMessage(userId, content),
+    });
     #logger;
     #options;
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
     #fetch;
     #routeReleases = [];
     #accessToken = { access_token: '', expires_in: 0, timestamp: 0 };
     #refreshPromise = null;
     #open = false;
     #started = false;
-    #unregisterAgent;
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('wecom', options.config.id);
         this.#options = options;
         this.#fetch = options.fetch ?? globalThis.fetch;
@@ -37,7 +59,6 @@ export class WecomEndpoint {
         this.#started = true;
         try {
             await this.#refreshAccessToken();
-            this.#unregisterAgent = registerWecomAgentEndpoint(this.#options.config.id, this);
             this.#routeReleases.push(...registerWecomWebhookRoutes(this.#options.http, this));
             this.#logger.debug(formatCompact({
                 endpoint: this.#options.config.id,
@@ -61,8 +82,6 @@ export class WecomEndpoint {
         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' }));
     }
@@ -152,12 +171,19 @@ export class WecomEndpoint {
     admit(msg) {
         if (!this.#open)
             return;
-        if (receiveWecomSideEvent(this.#options.sideEvents, String(this.#options.id), this.#options.config.id, msg, this.#logger)) {
+        void this.emitPlatform(msg.Event || msg.MsgType || 'event', msg).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'wecom_platform_event_failed',
+                event: msg.Event || msg.MsgType,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+        if (receiveWecomSideEvent((name, payload) => this.emit(name, payload), String(this.#options.id), this.#options.config.id, msg, this.#logger)) {
             return;
         }
         const chatType = resolveChatType(msg.FromUserName);
         const conversation = wecomInboundConversation(String(this.#options.id), msg);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: msg.MsgId || `${msg.CreateTime}` },
             content: formatInboundContent(msg),
@@ -178,7 +204,7 @@ export class WecomEndpoint {
             }));
         });
     }
-    async getUserInfo(userId) {
+    async #getUserInfo(userId) {
         try {
             const data = await this.#request('/cgi-bin/user/get', {
                 params: { userid: userId },
@@ -192,7 +218,7 @@ export class WecomEndpoint {
             return null;
         }
     }
-    async getDepartmentUsers(deptId) {
+    async #getDepartmentUsers(deptId) {
         try {
             const data = await this.#request('/cgi-bin/user/simplelist', {
                 params: { department_id: deptId },
@@ -206,7 +232,7 @@ export class WecomEndpoint {
             return [];
         }
     }
-    async getDepartmentList(deptId = 1) {
+    async #getDepartmentList(deptId = 1) {
         try {
             const data = await this.#request('/cgi-bin/department/list', {
                 params: { id: deptId },
@@ -220,7 +246,7 @@ export class WecomEndpoint {
             return [];
         }
     }
-    async sendTextMessage(userId, content) {
+    async #sendTextMessage(userId, content) {
         try {
             const endpointKey = String(this.#options.id);
             await this.send({

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 export { buildSendRequestBody, decryptMessage, extractEncryptFromXml, formatInboundContent, formatOutboundBody, getAesKey, normalizeEchostrParam, normalizeWebhookPath, parseXmlMessage, queryParam, readTextBody, resolveChatType, resolveWecomConfig, verifySignature, type AccessToken, type ResolvedWecomConfig, type WecomAdapterConfig, type WecomApiResponse, type WecomMessage, type WecomSendBody, type WecomWireSegment, } from './protocol.js';
-export { getWecomAgentDeps, registerWecomAgentEndpoint, setWecomAgentDeps, type WecomAgentDeps, type WecomAgentEndpoint, } from './wecom-agent-deps.js';
+export { wecomClient, type WecomClientEventMap } from './client.js';
 export { checkWecomPlatformPermit, normalizeWecomSenderForPermit, platformPermit, wecomGroupPermitResolver, } from './platform-permit.js';
-export { WecomEndpoint, type WecomEndpointOptions, type WecomFetch, } from './endpoint.js';
+export { WecomClient, WecomEndpoint, type WecomClientApi, type WecomEndpointOptions, type WecomFetch, } from './endpoint.js';
 export { buildMediaUploadForm, readOutboundImageMedia, resolveMediaBinary, type MediaBinary, type WecomMediaUploadResult, } from './media-upload.js';
 export { registerWecomWebhookRoutes, handleWecomVerificationRequest, handleWecomWebhookRequest, type WecomWebhookHandler, } from './webhook.js';

package/lib/index.js

@@ -1,6 +1,6 @@
 export { buildSendRequestBody, decryptMessage, extractEncryptFromXml, formatInboundContent, formatOutboundBody, getAesKey, normalizeEchostrParam, normalizeWebhookPath, parseXmlMessage, queryParam, readTextBody, resolveChatType, resolveWecomConfig, verifySignature, } from './protocol.js';
-export { getWecomAgentDeps, registerWecomAgentEndpoint, setWecomAgentDeps, } from './wecom-agent-deps.js';
+export { wecomClient } from './client.js';
 export { checkWecomPlatformPermit, normalizeWecomSenderForPermit, platformPermit, wecomGroupPermitResolver, } from './platform-permit.js';
-export { WecomEndpoint, } from './endpoint.js';
+export { WecomClient, WecomEndpoint, } from './endpoint.js';
 export { buildMediaUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
 export { registerWecomWebhookRoutes, handleWecomVerificationRequest, handleWecomWebhookRequest, } from './webhook.js';

package/lib/protocol.d.ts

@@ -84,7 +84,7 @@ export declare function verifySignature(token: string, timestamp: string, nonce:
 export declare function decryptMessage(encrypted: string, encodingAESKey: string, corpId: string): string | null;
 export declare function extractEncryptFromXml(xml: string): string | null;
 export declare function parseXmlMessage(xml: string): WecomMessage | null;
-/** Build inbound text for MessageGateway.receive. */
+/** Build inbound text for OutboundMessageService.receive. */
 export declare function formatInboundContent(msg: WecomMessage): string;
 export declare function resolveChatType(fromUserName: string): 'group' | 'private';
 /**

package/lib/protocol.js

@@ -128,7 +128,7 @@ export function parseXmlMessage(xml) {
         return null;
     }
 }
-/** Build inbound text for MessageGateway.receive. */
+/** Build inbound text for OutboundMessageService.receive. */
 export function formatInboundContent(msg) {
     switch (msg.MsgType) {
         case 'text':

package/lib/side-event-dispatch.d.ts

@@ -1,4 +1,4 @@
-import type { SideEventGateway } from '@zhin.js/core/runtime';
+import type { EndpointEventEmitter } from 'zhin.js/adapter';
 import { type getAdapterLogger } from '@zhin.js/logger';
 import { type WecomMessage } from './protocol.js';
-export declare function receiveWecomSideEvent(sideEvents: SideEventGateway | undefined, endpointKey: string, configId: string, msg: WecomMessage, logger: ReturnType<typeof getAdapterLogger>): boolean;
+export declare function receiveWecomSideEvent(emit: EndpointEventEmitter, endpointKey: string, configId: string, msg: WecomMessage, logger: ReturnType<typeof getAdapterLogger>): boolean;

package/lib/side-event-dispatch.js

@@ -13,12 +13,12 @@ function mapWecomEventParts(eventName) {
             return { scene_type: 'wecom', sub_type: eventName || 'unknown' };
     }
 }
-export function receiveWecomSideEvent(sideEvents, endpointKey, configId, msg, logger) {
-    if (!sideEvents || msg.MsgType !== 'event')
+export function receiveWecomSideEvent(emit, endpointKey, configId, msg, logger) {
+    if (msg.MsgType !== 'event')
         return false;
     const eventName = msg.Event ?? 'unknown';
     if (eventName === 'enter_agent') {
-        void sideEvents.receiveSystem(buildSystem(msg, {
+        void emit('system.receive', buildSystem(msg, {
             $id: `wecom:enter_agent:${msg.FromUserName}:${msg.CreateTime ?? Date.now()}`,
             $adapter: 'wecom',
             $endpoint: configId,
@@ -41,7 +41,7 @@ export function receiveWecomSideEvent(sideEvents, endpointKey, configId, msg, lo
     if (!parts)
         return false;
     const sceneType = resolveChatType(msg.FromUserName);
-    void sideEvents.receiveNotice(buildNotice(msg, {
+    void emit('notice.receive', buildNotice(msg, {
         $id: `wecom:${eventName}:${msg.FromUserName}:${msg.CreateTime ?? Date.now()}`,
         $adapter: 'wecom',
         $endpoint: configId,

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-wecom",
-  "version": "4.0.14",
+  "version": "5.0.1",
   "description": "Zhin.js WeCom (企业微信) adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,21 +34,22 @@
     "directory": "plugins/adapters/wecom"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.11",
-    "@zhin.js/core": "1.5.12",
-    "@zhin.js/host-http": "1.0.11",
+    "@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.1.11",
-    "@zhin.js/agent": "1.1.14",
-    "@zhin.js/command": "1.0.15",
-    "@zhin.js/core": "1.5.12",
-    "@zhin.js/host-http": "1.0.11",
-    "@zhin.js/permission": "1.0.3",
-    "zhin.js": "6.0.12"
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/agent": "1.1.16",
+    "@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.14",
-    "zhin.js": "6.0.12"
+    "@zhin.js/agent": "1.1.16",
+    "zhin.js": "6.0.14"
   },
   "files": [
     "adapters",

package/src/client.ts

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

package/src/endpoint.ts

@@ -1,12 +1,15 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
  * WecomEndpoint — lifecycle, outbound send, inbound admit, OpenAPI helpers for agent tools.
  */
-import type { EndpointInstance, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import {
+  createRecallEndpointControl,
+  type EndpointControl,
+  type EndpointSendRequest,
+} from 'zhin.js/adapter';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
-import { registerWecomAgentEndpoint } from './wecom-agent-deps.js';
 import {
   buildMediaUploadForm,
   readOutboundImageMedia,
@@ -43,31 +46,52 @@ export type WecomFetch = (
 
 export interface WecomEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: ResolvedWecomConfig;
   readonly fetch?: WecomFetch;
 }
 
+export interface WecomClientApi {
+  getUserInfo(userId: string): Promise<unknown>;
+  getDepartmentUsers(deptId: number): Promise<unknown[]>;
+  getDepartmentList(deptId?: number): Promise<unknown[]>;
+  sendTextMessage(userId: string, content: string): Promise<boolean>;
+}
+
+/** WeCom API surface exposed to plugin events without Endpoint lifecycle methods. */
+export class WecomClient implements WecomClientApi {
+  constructor(readonly api: WecomClientApi) {}
+  getUserInfo = (userId: string) => this.api.getUserInfo(userId);
+  getDepartmentUsers = (deptId: number) => this.api.getDepartmentUsers(deptId);
+  getDepartmentList = (deptId?: number) => this.api.getDepartmentList(deptId);
+  sendTextMessage = (userId: string, content: string) => this.api.sendTextMessage(userId, content);
+}
+
 /**
  * 企业微信服务端 API 无 bot 群列表/群成员列表接口（客户群接口属「客户联系」
  * 独立授权域，非 bot 社交面），好友/频道概念亦不存在；
  * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
  */
-export class WecomEndpoint implements EndpointInstance {
+export class WecomEndpoint extends Endpoint<WecomClient> {
+  readonly client = new WecomClient({
+    getUserInfo: (userId) => this.#getUserInfo(userId),
+    getDepartmentUsers: (deptId) => this.#getDepartmentUsers(deptId),
+    getDepartmentList: (deptId) => this.#getDepartmentList(deptId),
+    sendTextMessage: (userId, content) => this.#sendTextMessage(userId, content),
+  });
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: WecomEndpointOptions;
+  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
   readonly #fetch: WecomFetch;
   #routeReleases: HttpRouteRegistration[] = [];
   #accessToken: AccessToken = { access_token: '', expires_in: 0, timestamp: 0 };
   #refreshPromise: Promise<string> | null = null;
   #open = false;
   #started = false;
-  #unregisterAgent?: () => void;
 
   constructor(options: WecomEndpointOptions) {
+    super();
     this.#logger = getAdapterLogger('wecom', options.config.id);
     this.#options = options;
     this.#fetch = options.fetch ?? globalThis.fetch;
@@ -87,7 +111,6 @@ export class WecomEndpoint implements EndpointInstance {
     this.#started = true;
     try {
       await this.#refreshAccessToken();
-      this.#unregisterAgent = registerWecomAgentEndpoint(this.#options.config.id, this);
       this.#routeReleases.push(...registerWecomWebhookRoutes(this.#options.http, this));
       this.#logger.debug(formatCompact({
         endpoint: this.#options.config.id,
@@ -112,8 +135,6 @@ export class WecomEndpoint 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' }));
   }
@@ -204,8 +225,15 @@ export class WecomEndpoint implements EndpointInstance {
   /** Test / internal: admit a parsed message when open (non-webhook path). */
   admit(msg: WecomMessage): void {
     if (!this.#open) return;
+    void this.emitPlatform(msg.Event || msg.MsgType || 'event', msg).catch((error) => {
+      this.#logger.warn(formatCompact({
+        op: 'wecom_platform_event_failed',
+        event: msg.Event || msg.MsgType,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    });
     if (receiveWecomSideEvent(
-      this.#options.sideEvents,
+      (name, payload) => this.emit(name, payload),
       String(this.#options.id),
       this.#options.config.id,
       msg,
@@ -215,7 +243,7 @@ export class WecomEndpoint implements EndpointInstance {
     }
     const chatType = resolveChatType(msg.FromUserName);
     const conversation = wecomInboundConversation(String(this.#options.id), msg);
-    void this.#options.gateway.receive({
+    void this.emit('message.receive', {
       conversation,
       message: { conversation, id: msg.MsgId || `${msg.CreateTime}` },
       content: formatInboundContent(msg),
@@ -237,7 +265,7 @@ export class WecomEndpoint implements EndpointInstance {
     });
   }
 
-  async getUserInfo(userId: string): Promise<WecomApiResponse | null> {
+  async #getUserInfo(userId: string): Promise<WecomApiResponse | null> {
     try {
       const data = await this.#request('/cgi-bin/user/get', {
         params: { userid: userId },
@@ -250,7 +278,7 @@ export class WecomEndpoint implements EndpointInstance {
     }
   }
 
-  async getDepartmentUsers(deptId: number): Promise<unknown[]> {
+  async #getDepartmentUsers(deptId: number): Promise<unknown[]> {
     try {
       const data = await this.#request('/cgi-bin/user/simplelist', {
         params: { department_id: deptId },
@@ -263,7 +291,7 @@ export class WecomEndpoint implements EndpointInstance {
     }
   }
 
-  async getDepartmentList(deptId: number = 1): Promise<unknown[]> {
+  async #getDepartmentList(deptId: number = 1): Promise<unknown[]> {
     try {
       const data = await this.#request('/cgi-bin/department/list', {
         params: { id: deptId },
@@ -276,7 +304,7 @@ export class WecomEndpoint implements EndpointInstance {
     }
   }
 
-  async sendTextMessage(userId: string, content: string): Promise<boolean> {
+  async #sendTextMessage(userId: string, content: string): Promise<boolean> {
     try {
       const endpointKey = String(this.#options.id);
       await this.send({

package/src/index.ts

@@ -22,13 +22,7 @@ export {
   type WecomWireSegment,
 } from './protocol.js';
 
-export {
-  getWecomAgentDeps,
-  registerWecomAgentEndpoint,
-  setWecomAgentDeps,
-  type WecomAgentDeps,
-  type WecomAgentEndpoint,
-} from './wecom-agent-deps.js';
+export { wecomClient, type WecomClientEventMap } from './client.js';
 
 export {
   checkWecomPlatformPermit,
@@ -38,7 +32,9 @@ export {
 } from './platform-permit.js';
 
 export {
+  WecomClient,
   WecomEndpoint,
+  type WecomClientApi,
   type WecomEndpointOptions,
   type WecomFetch,
 } from './endpoint.js';

package/src/protocol.ts

@@ -227,7 +227,7 @@ export function parseXmlMessage(xml: string): WecomMessage | null {
   }
 }
 
-/** Build inbound text for MessageGateway.receive. */
+/** Build inbound text for OutboundMessageService.receive. */
 export function formatInboundContent(msg: WecomMessage): string {
   switch (msg.MsgType) {
     case 'text':

package/src/side-event-dispatch.ts

@@ -1,5 +1,5 @@
 import { buildNotice, buildSystem, senderFromId } from '@zhin.js/core';
-import type { SideEventGateway } from '@zhin.js/core/runtime';
+import type { EndpointEventEmitter } from 'zhin.js/adapter';
 import { formatCompact, type getAdapterLogger } from '@zhin.js/logger';
 import { resolveChatType, type WecomMessage } from './protocol.js';
 
@@ -17,16 +17,16 @@ function mapWecomEventParts(eventName: string): { scene_type: string; sub_type:
 }
 
 export function receiveWecomSideEvent(
-  sideEvents: SideEventGateway | undefined,
+  emit: EndpointEventEmitter,
   endpointKey: string,
   configId: string,
   msg: WecomMessage,
   logger: ReturnType<typeof getAdapterLogger>,
 ): boolean {
-  if (!sideEvents || msg.MsgType !== 'event') return false;
+  if (msg.MsgType !== 'event') return false;
   const eventName = msg.Event ?? 'unknown';
   if (eventName === 'enter_agent') {
-    void sideEvents.receiveSystem(buildSystem(msg, {
+    void emit('system.receive', buildSystem(msg, {
       $id: `wecom:enter_agent:${msg.FromUserName}:${msg.CreateTime ?? Date.now()}`,
       $adapter: 'wecom' as never,
       $endpoint: configId,
@@ -48,7 +48,7 @@ export function receiveWecomSideEvent(
   const parts = mapWecomEventParts(eventName);
   if (!parts) return false;
   const sceneType = resolveChatType(msg.FromUserName);
-  void sideEvents.receiveNotice(buildNotice(msg, {
+  void emit('notice.receive', buildNotice(msg, {
     $id: `wecom:${eventName}:${msg.FromUserName}:${msg.CreateTime ?? Date.now()}`,
     $adapter: 'wecom' as never,
     $endpoint: configId,

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

@@ -1,17 +0,0 @@
-/**
- * Agent tool deps for wecom (get_user / departments / send_text).
- * Endpoints register themselves on start; tools look up by endpoint id.
- */
-export interface WecomAgentEndpoint {
-    getUserInfo(userId: string): Promise<unknown>;
-    getDepartmentUsers(deptId: number): Promise<unknown[]>;
-    getDepartmentList(deptId?: number): Promise<unknown[]>;
-    sendTextMessage(userId: string, content: string): Promise<boolean>;
-}
-export interface WecomAgentDeps {
-    getEndpoint: (endpointKey: string) => WecomAgentEndpoint;
-}
-export declare function registerWecomAgentEndpoint(endpointKey: string, endpoint: WecomAgentEndpoint): () => void;
-/** Optional override used by tests / transitional callers. Pass `null` to clear. */
-export declare function setWecomAgentDeps(deps: WecomAgentDeps | null): void;
-export declare function getWecomAgentDeps(): WecomAgentDeps;

package/lib/wecom-agent-deps.js

@@ -1,30 +0,0 @@
-/**
- * Agent tool deps for wecom (get_user / departments / send_text).
- * Endpoints register themselves on start; tools look up by endpoint id.
- */
-const endpoints = new Map();
-let override = null;
-export function registerWecomAgentEndpoint(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 setWecomAgentDeps(deps) {
-    override = deps;
-}
-export function getWecomAgentDeps() {
-    if (override)
-        return override;
-    return {
-        getEndpoint(endpointKey) {
-            const endpoint = endpoints.get(endpointKey);
-            if (!endpoint)
-                throw new Error(`Endpoint ${endpointKey} 不存在`);
-            return endpoint;
-        },
-    };
-}

package/src/wecom-agent-deps.ts

@@ -1,46 +0,0 @@
-/**
- * Agent tool deps for wecom (get_user / departments / send_text).
- * Endpoints register themselves on start; tools look up by endpoint id.
- */
-
-export interface WecomAgentEndpoint {
-  getUserInfo(userId: string): Promise<unknown>;
-  getDepartmentUsers(deptId: number): Promise<unknown[]>;
-  getDepartmentList(deptId?: number): Promise<unknown[]>;
-  sendTextMessage(userId: string, content: string): Promise<boolean>;
-}
-
-export interface WecomAgentDeps {
-  getEndpoint: (endpointKey: string) => WecomAgentEndpoint;
-}
-
-const endpoints = new Map<string, WecomAgentEndpoint>();
-let override: WecomAgentDeps | null = null;
-
-export function registerWecomAgentEndpoint(
-  endpointKey: string,
-  endpoint: WecomAgentEndpoint,
-): () => 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 setWecomAgentDeps(deps: WecomAgentDeps | null): void {
-  override = deps;
-}
-
-export function getWecomAgentDeps(): WecomAgentDeps {
-  if (override) return override;
-  return {
-    getEndpoint(endpointKey) {
-      const endpoint = endpoints.get(endpointKey);
-      if (!endpoint) throw new Error(`Endpoint ${endpointKey} 不存在`);
-      return endpoint;
-    },
-  };
-}