@zhin.js/adapter-wechat-mp 6.0.0 → 6.0.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @zhin.js/adapter-wechat-mp
 
+## 6.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 [4e8117c]
+- Updated dependencies [54bfd6b]
+- Updated dependencies [12025ee]
+- Updated dependencies [09b14d6]
+- Updated dependencies [1fc78bc]
+  - @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
+
 ## 6.0.0
 
 ### Patch Changes

package/README.md

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

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

package/adapters/wechat-mp.ts

@@ -2,7 +2,6 @@
  * Convention entry: discover `adapters/wechat-mp.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { WeChatMpEndpoint } from '../src/endpoint.js';
 import {
@@ -12,7 +11,8 @@ import {
 import { wechatMpRuntimeStateToken } from '../src/wechat-mp-runtime-state.js';
 
 export { WeChatMpEndpoint } from '../src/endpoint.js';
-export type { WeChatMpEndpointOptions, WeChatMpFetch } from '../src/endpoint.js';
+export type { WeChatMpEndpointOptions } from '../src/endpoint.js';
+export type { WeChatMpFetch } from '../src/client.js';
 
 export default defineAdapter<WeChatMpAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
@@ -31,8 +31,6 @@ export default defineAdapter<WeChatMpAdapterConfig>({
     });
     return new WeChatMpEndpoint({
       id: context.id,
-      gateway: context.use(messageGatewayToken),
-      sideEvents: context.use(sideEventGatewayToken),
       http: context.use(httpHostToken),
       config,
     });

package/lib/client.d.ts

@@ -0,0 +1,32 @@
+import type { ResolvedWeChatMpConfig, WeChatAPIResponse } from './protocol.js';
+export type WeChatMpFetch = (url: string, init?: {
+    readonly method?: string;
+    readonly body?: unknown;
+    readonly headers?: Record<string, string>;
+}) => Promise<{
+    readonly data: unknown;
+}>;
+/** Direct WeChat Official Account API client exposed to plugins. */
+export declare class WeChatMpClient {
+    #private;
+    readonly config: ResolvedWeChatMpConfig;
+    readonly fetch: WeChatMpFetch;
+    constructor(config: ResolvedWeChatMpConfig, fetch: WeChatMpFetch);
+    get accessToken(): string | null;
+    get tokenExpired(): boolean;
+    refreshAccessToken(): Promise<string>;
+    request<T = unknown>(path: string, init?: Parameters<WeChatMpFetch>[1]): Promise<T>;
+    sendCustomerService(messageData: unknown): Promise<WeChatAPIResponse>;
+    uploadMedia(type: 'image' | 'voice' | 'video', body: unknown): Promise<string>;
+    getFollowerIds(): Promise<readonly string[]>;
+}
+export type WeChatMpClientEventMap = Record<string, unknown>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly 'wechat-mp': {
+            readonly client: WeChatMpClient;
+            readonly events: WeChatMpClientEventMap;
+        };
+    }
+}
+export declare const wechatMpClient: import("@zhin.js/adapter").EndpointClientToken<WeChatMpClient, WeChatMpClientEventMap>;

package/lib/client.js

@@ -0,0 +1,70 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+const TOKEN_INVALID_ERRCODES = new Set([40001, 40014, 42001]);
+/** Direct WeChat Official Account API client exposed to plugins. */
+export class WeChatMpClient {
+    config;
+    fetch;
+    #accessToken = null;
+    #tokenExpireTime = 0;
+    constructor(config, fetch) {
+        this.config = config;
+        this.fetch = fetch;
+    }
+    get accessToken() {
+        return this.#accessToken;
+    }
+    get tokenExpired() {
+        return !this.#accessToken || Date.now() >= this.#tokenExpireTime;
+    }
+    async refreshAccessToken() {
+        const { appId, appSecret } = this.config;
+        const url = `https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=${appId}&secret=${appSecret}`;
+        const response = await this.fetch(url);
+        const data = response.data;
+        if (!data.access_token) {
+            throw new Error(data.errmsg
+                ? `Failed to get access token: ${data.errcode} ${data.errmsg}`
+                : 'Failed to get access token');
+        }
+        this.#accessToken = data.access_token;
+        this.#tokenExpireTime = Date.now() + (data.expires_in - 300) * 1000;
+        return data.access_token;
+    }
+    async request(path, init) {
+        if (this.tokenExpired)
+            await this.refreshAccessToken();
+        const separator = path.includes('?') ? '&' : '?';
+        const response = await this.fetch(`https://api.weixin.qq.com${path}${separator}access_token=${this.#accessToken}`, init);
+        return response.data;
+    }
+    async sendCustomerService(messageData) {
+        let result = await this.request('/cgi-bin/message/custom/send', { method: 'POST', body: messageData });
+        if (result.errcode && TOKEN_INVALID_ERRCODES.has(Number(result.errcode))) {
+            await this.refreshAccessToken();
+            result = await this.request('/cgi-bin/message/custom/send', { method: 'POST', body: messageData });
+        }
+        return result;
+    }
+    async uploadMedia(type, body) {
+        const data = await this.request(`/cgi-bin/media/upload?type=${type}`, { method: 'POST', body });
+        if (data.media_id)
+            return data.media_id;
+        throw new Error(`WeChat media upload failed: ${data.errcode ?? 'unknown'} ${data.errmsg ?? ''}`.trim());
+    }
+    async getFollowerIds() {
+        const followers = [];
+        let nextOpenid = '';
+        do {
+            const data = await this.request(`/cgi-bin/user/get?next_openid=${encodeURIComponent(nextOpenid)}`);
+            if (data.errcode && data.errcode !== 0) {
+                throw new Error(`WeChat API error: ${data.errcode} - ${data.errmsg}`);
+            }
+            followers.push(...(data.data?.openid ?? []).filter(Boolean));
+            if (Number(data.count ?? 0) < 10_000)
+                break;
+            nextOpenid = data.next_openid ?? '';
+        } while (nextOpenid);
+        return Object.freeze(followers);
+    }
+}
+export const wechatMpClient = defineEndpointClient('wechat-mp');

package/lib/endpoint.d.ts

@@ -1,32 +1,24 @@
-import type { EndpointFriend, EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import { Endpoint } from 'zhin.js/adapter';
+import type { EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type ResolvedWeChatMpConfig, type WeChatMessage } from './protocol.js';
-export type WeChatMpFetch = (url: string, init?: {
-    readonly method?: string;
-    readonly body?: unknown;
-    readonly headers?: Record<string, string>;
-}) => Promise<{
-    readonly data: unknown;
-}>;
+import { WeChatMpClient, type WeChatMpFetch } from './client.js';
 export interface WeChatMpEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: ResolvedWeChatMpConfig;
     readonly fetch?: WeChatMpFetch;
 }
-export declare class WeChatMpEndpoint implements EndpointInstance {
+export declare class WeChatMpEndpoint extends Endpoint<WeChatMpClient> {
     #private;
+    readonly client: WeChatMpClient;
     readonly management: EndpointManagement;
     constructor(options: WeChatMpEndpointOptions);
     /** Used by webhook handler. */
     get isOpen(): boolean;
     get config(): ResolvedWeChatMpConfig;
     get id(): CapabilityId;
-    get gateway(): MessageGateway;
     /** 微信 5s 重推去重：见过该 MsgId 时返回首次回复 XML（含空串=success）。 */
     getCachedReply(msgId: string): string | undefined;
     cacheReply(msgId: string, replyXML: string): void;
@@ -36,11 +28,5 @@ export declare class WeChatMpEndpoint implements EndpointInstance {
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     /** Test / internal: admit a parsed message when open (non-webhook path). */
-    admit(msg: WeChatMessage): void;
-    /**
-     * 关注者列表（GET /cgi-bin/user/get，按 next_openid 分页，每页最多 10000）。
-     * 该接口只回 openid 不回昵称；昵称需逐个调 user/info（成本高且依赖用户授权），
-     * 这里 nickname 用 openid 占位，由 Console 侧自行理解。
-     */
-    getFollowers(): Promise<readonly EndpointFriend[]>;
+    admit(msg: WeChatMessage): void | Promise<unknown>;
 }

package/lib/endpoint.js

@@ -1,3 +1,4 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
  * WeChatMpEndpoint — lifecycle, outbound, admit, access token refresh.
  */
@@ -8,8 +9,7 @@ import { buildMediaUploadForm, readOutboundMedia, resolveMediaBinary, } from './
 import { getPassiveReplyCapture, recordPassiveReplyText, } from './passive-reply.js';
 import { registerWeChatMpWebhookRoutes } from './webhook.js';
 import { receiveWeChatMpSideEvent } from './side-event-dispatch.js';
-/** token 失效类错误码：40001/40014 invalid access_token、42001 access_token expired。 */
-const TOKEN_INVALID_ERRCODES = new Set([40001, 40014, 42001]);
+import { WeChatMpClient } from './client.js';
 /**
  * canonical 媒体段类型 → 微信 /cgi-bin/media/upload 的 type。
  * 客服消息无 file 投递面，file 段不可投递。
@@ -28,24 +28,25 @@ function defaultFetch(url, init) {
         headers: init?.headers,
     }).then((response) => ({ data: response.data }));
 }
-export class WeChatMpEndpoint {
+export class WeChatMpEndpoint extends Endpoint {
+    client;
     #logger;
     #options;
     #fetch;
     #routeReleases = [];
-    #accessToken = null;
-    #tokenExpireTime = 0;
     #tokenRefreshTimer;
     /** MsgId → 首次回复 XML（微信 5s 重推去重，有界 LRU）。 */
     #replyCache = new Map();
     static #REPLY_CACHE_LIMIT = 1000;
     #open = false;
     #started = false;
-    management = createWeChatMpEndpointManagement(this);
+    management = createWeChatMpEndpointManagement(() => this.client);
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('wechat-mp', options.config.id);
         this.#options = options;
         this.#fetch = options.fetch ?? defaultFetch;
+        this.client = new WeChatMpClient(options.config, this.#fetch);
     }
     /** Used by webhook handler. */
     get isOpen() {
@@ -57,9 +58,6 @@ export class WeChatMpEndpoint {
     get id() {
         return this.#options.id;
     }
-    get gateway() {
-        return this.#options.gateway;
-    }
     /** 微信 5s 重推去重：见过该 MsgId 时返回首次回复 XML（含空串=success）。 */
     getCachedReply(msgId) {
         return this.#replyCache.get(msgId);
@@ -80,7 +78,7 @@ export class WeChatMpEndpoint {
             return;
         this.#started = true;
         try {
-            await this.#refreshAccessToken();
+            await this.client.refreshAccessToken();
             this.#routeReleases.push(...registerWeChatMpWebhookRoutes(this.#options.http, this));
             this.#startTokenRefreshTimer();
             this.#logger.debug(formatCompact({
@@ -133,11 +131,17 @@ export class WeChatMpEndpoint {
     admit(msg) {
         if (!this.#open)
             return;
-        if (receiveWeChatMpSideEvent(this.#options.sideEvents, this.#options.config.id, msg, this.#logger)) {
-            return;
+        void this.emitPlatform(msg.Event ? `${msg.MsgType}.${msg.Event}` : msg.MsgType, msg).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'wechat_mp_platform_event_failed',
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+        if (receiveWeChatMpSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, msg, this.#logger)) {
+            return undefined;
         }
         const conversation = wechatMpInboundConversation(String(this.#options.id), msg);
-        void this.#options.gateway.receive({
+        return this.emit('message.receive', {
             conversation,
             message: { conversation, id: formatInboundId(msg) },
             content: formatInboundContent(msg),
@@ -158,21 +162,9 @@ export class WeChatMpEndpoint {
     }
     async #sendCustomerService(target, payload) {
         // 发送前检查过期（不只判 null）：过期 token 直接刷新，不白跑一次 40001。
-        if (!this.#accessToken || Date.now() >= this.#tokenExpireTime) {
-            await this.#refreshAccessToken();
-        }
         const materialized = await this.#materializeOutboundMedia(payload);
         const messageData = formatCustomerServiceBody(target, materialized);
-        let result = await this.#postCustomerService(messageData);
-        if (result.errcode && TOKEN_INVALID_ERRCODES.has(Number(result.errcode))) {
-            // 对端提前作废 token（多端共用等）：刷新后重试一次。
-            this.#logger.warn(formatCompact({
-                op: 'wechat_mp_token_invalid_retry',
-                errcode: result.errcode,
-            }));
-            await this.#refreshAccessToken();
-            result = await this.#postCustomerService(messageData);
-        }
+        const result = await this.client.sendCustomerService(messageData);
         if (result.errcode && result.errcode !== 0) {
             throw new Error(`WeChat API error: ${result.errcode} - ${result.errmsg}`);
         }
@@ -248,77 +240,25 @@ export class WeChatMpEndpoint {
     async #uploadMedia(type, media) {
         const binary = await resolveMediaBinary(media);
         const form = buildMediaUploadForm(binary);
-        const url = `https://api.weixin.qq.com/cgi-bin/media/upload?access_token=${this.#accessToken}&type=${type}`;
-        const response = await this.#fetch(url, { method: 'POST', body: form });
-        const data = response.data;
-        if (data.media_id)
-            return data.media_id;
-        throw new Error(`WeChat media upload failed: ${data.errcode ?? 'unknown'} ${data.errmsg ?? ''}`.trim());
-    }
-    async #postCustomerService(messageData) {
-        const url = `https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=${this.#accessToken}`;
-        const response = await this.#fetch(url, { method: 'POST', body: messageData });
-        return response.data;
-    }
-    /**
-     * 关注者列表（GET /cgi-bin/user/get，按 next_openid 分页，每页最多 10000）。
-     * 该接口只回 openid 不回昵称；昵称需逐个调 user/info（成本高且依赖用户授权），
-     * 这里 nickname 用 openid 占位，由 Console 侧自行理解。
-     */
-    async getFollowers() {
-        if (!this.#accessToken || Date.now() >= this.#tokenExpireTime) {
-            await this.#refreshAccessToken();
-        }
-        const friends = [];
-        let nextOpenid = '';
-        do {
-            const url = `https://api.weixin.qq.com/cgi-bin/user/get?access_token=${this.#accessToken}&next_openid=${encodeURIComponent(nextOpenid)}`;
-            const response = await this.#fetch(url);
-            const data = response.data;
-            if (data.errcode && data.errcode !== 0) {
-                throw new Error(`WeChat API error: ${data.errcode} - ${data.errmsg}`);
-            }
-            for (const openid of data.data?.openid ?? []) {
-                if (typeof openid === 'string' && openid) {
-                    friends.push({ user_id: openid, nickname: openid, remark: '' });
-                }
-            }
-            const fetched = Number(data.count ?? 0);
-            nextOpenid = typeof data.next_openid === 'string' ? data.next_openid : '';
-            // 满页（10000）才可能有下一页；不足一页即到底，避免依赖 next_openid 回显语义。
-            if (fetched < 10_000)
-                break;
-        } while (nextOpenid);
-        return friends;
-    }
-    async #refreshAccessToken() {
-        const { appId, appSecret } = this.#options.config;
-        const url = `https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=${appId}&secret=${appSecret}`;
-        const response = await this.#fetch(url);
-        const data = response.data;
-        if (data.access_token) {
-            this.#accessToken = data.access_token;
-            this.#tokenExpireTime = Date.now() + (data.expires_in - 300) * 1000;
-            this.#logger.debug(formatCompact({ op: 'token_refresh' }));
-            return;
-        }
-        throw new Error(data.errmsg
-            ? `Failed to get access token: ${data.errcode} ${data.errmsg}`
-            : 'Failed to get access token');
+        return this.client.uploadMedia(type, form);
     }
     #startTokenRefreshTimer() {
         this.#tokenRefreshTimer = setInterval(() => {
-            if (Date.now() >= this.#tokenExpireTime) {
-                void this.#refreshAccessToken().catch((error) => {
+            if (this.client.tokenExpired) {
+                void this.client.refreshAccessToken().catch((error) => {
                     this.#logger.error('Failed to refresh access token in timer:', error);
                 });
             }
         }, 3_600_000);
     }
 }
-function createWeChatMpEndpointManagement(endpoint) {
+function createWeChatMpEndpointManagement(requireClient) {
     return Object.freeze({
         // 公众号无群/频道概念；关注者即"好友"（nickname 为 openid 占位，见 getFollowers）。
-        listFriends: () => endpoint.getFollowers(),
+        listFriends: async () => (await requireClient().getFollowerIds()).map((openid) => ({
+            user_id: openid,
+            nickname: openid,
+            remark: '',
+        })),
     });
 }

package/lib/index.d.ts

@@ -1,5 +1,6 @@
 export { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, extractOutboundText, formatCustomerServiceBody, formatInboundContent, formatInboundId, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, resolveWeChatMpConfig, verifySignature, type ResolvedWeChatMpConfig, type TokenResponse, type WeChatAPIResponse, type WeChatMessage, type WeChatMpAdapterConfig, type WeChatWireSegment, } from './protocol.js';
 export { getPassiveReplyCapture, recordPassiveReplyText, runWithPassiveReplyCapture, type PassiveReplyCapture, } from './passive-reply.js';
-export { WeChatMpEndpoint, type WeChatMpEndpointOptions, type WeChatMpFetch, } from './endpoint.js';
+export { WeChatMpClient, wechatMpClient, type WeChatMpClientEventMap, type WeChatMpFetch, } from './client.js';
+export { WeChatMpEndpoint, type WeChatMpEndpointOptions, } from './endpoint.js';
 export { buildMediaUploadForm, readOutboundMedia, resolveMediaBinary, type MediaBinary, type WeChatMediaUploadResult, } from './media-upload.js';
 export { registerWeChatMpWebhookRoutes, handleWeChatMpVerification, handleWeChatMpMessage, collectPassiveReply, type WeChatMpWebhookHandler, } from './webhook.js';

package/lib/index.js

@@ -1,5 +1,6 @@
 export { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, extractOutboundText, formatCustomerServiceBody, formatInboundContent, formatInboundId, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, resolveWeChatMpConfig, verifySignature, } from './protocol.js';
 export { getPassiveReplyCapture, recordPassiveReplyText, runWithPassiveReplyCapture, } from './passive-reply.js';
+export { WeChatMpClient, wechatMpClient, } from './client.js';
 export { WeChatMpEndpoint, } from './endpoint.js';
 export { buildMediaUploadForm, readOutboundMedia, resolveMediaBinary, } from './media-upload.js';
 export { registerWeChatMpWebhookRoutes, handleWeChatMpVerification, handleWeChatMpMessage, collectPassiveReply, } from './webhook.js';

package/lib/protocol.d.ts

@@ -112,7 +112,7 @@ export declare function wechatMpInboundConversation(endpointKey: string, msg: We
  * 避免只用秒级 CreateTime 时同秒多事件 id 碰撞。
  */
 export declare function formatInboundId(msg: WeChatMessage): string;
-/** Build inbound text for MessageGateway.receive. */
+/** Build inbound text for OutboundMessageService.receive. */
 export declare function formatInboundContent(msg: WeChatMessage): string;
 /**
  * Built-in passive XML for subscribe etc. Empty string = fall through to gateway.

package/lib/protocol.js

@@ -192,7 +192,7 @@ export function formatInboundId(msg) {
         .filter((part) => part != null && part !== '')
         .join(':');
 }
-/** 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 WeChatMessage } from './protocol.js';
-export declare function receiveWeChatMpSideEvent(sideEvents: SideEventGateway | undefined, configId: string, msg: WeChatMessage, logger: ReturnType<typeof getAdapterLogger>): boolean;
+export declare function receiveWeChatMpSideEvent(emit: EndpointEventEmitter, configId: string, msg: WeChatMessage, logger: ReturnType<typeof getAdapterLogger>): boolean;

package/lib/side-event-dispatch.js

@@ -11,12 +11,12 @@ function mapWeChatMpEventParts(eventName) {
             return { scene_type: 'wechat-mp', sub_type: eventName || 'unknown' };
     }
 }
-export function receiveWeChatMpSideEvent(sideEvents, configId, msg, logger) {
-    if (!sideEvents || msg.MsgType !== 'event')
+export function receiveWeChatMpSideEvent(emit, configId, msg, logger) {
+    if (msg.MsgType !== 'event')
         return false;
     const eventName = msg.Event ?? 'unknown';
     const parts = mapWeChatMpEventParts(eventName);
-    void sideEvents.receiveNotice(buildNotice(msg, {
+    void emit('notice.receive', buildNotice(msg, {
         $id: `wechat-mp:${formatInboundId(msg)}`,
         $adapter: 'wechat-mp',
         $endpoint: configId,

package/lib/webhook.d.ts

@@ -2,7 +2,6 @@
  * WeChat MP webhook HTTP: URL verification + inbound message handling.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type ResolvedWeChatMpConfig, type WeChatMessage } from './protocol.js';
@@ -10,8 +9,7 @@ export interface WeChatMpWebhookHandler {
     readonly config: ResolvedWeChatMpConfig;
     readonly isOpen: boolean;
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    admit(msg: WeChatMessage): void;
+    admit(msg: WeChatMessage): void | Promise<unknown>;
     /** MsgId 去重缓存（可选；实现见 WeChatMpEndpoint）。 */
     getCachedReply?(msgId: string): string | undefined;
     cacheReply?(msgId: string, replyXML: string): void;

package/lib/webhook.js

@@ -1,6 +1,6 @@
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { getPassiveReplyCapture, runWithPassiveReplyCapture, } from './passive-reply.js';
-import { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, formatInboundContent, formatInboundId, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, verifySignature, wechatMpInboundConversation, } from './protocol.js';
+import { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, verifySignature, wechatMpInboundConversation, } from './protocol.js';
 const logger = getLogger('wechat-mp');
 export function registerWeChatMpWebhookRoutes(http, handler) {
     const path = handler.config.path;
@@ -134,18 +134,7 @@ export async function collectPassiveReply(handler, wechatMsg) {
     const text = await runWithPassiveReplyCapture(async () => {
         const conversation = wechatMpInboundConversation(String(handler.id), wechatMsg);
         await Promise.race([
-            handler.gateway.receive({
-                conversation,
-                message: { conversation, id: formatInboundId(wechatMsg) },
-                content: formatInboundContent(wechatMsg),
-                sender: { id: wechatMsg.FromUserName },
-                endpointId: handler.config.id,
-                metadata: Object.freeze({
-                    msgType: wechatMsg.MsgType,
-                    event: wechatMsg.Event,
-                    toUserName: wechatMsg.ToUserName,
-                }),
-            }),
+            Promise.resolve(handler.admit(wechatMsg)),
             new Promise((resolve) => setTimeout(resolve, timeoutMs)),
         ]);
         return getPassiveReplyCapture()?.text ?? null;

package/lib/wechat-mp-endpoint-commands.d.ts

@@ -1 +1 @@
-export declare const wechatMpEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;
+export declare const wechatMpEndpointCommands: 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-wechat-mp",
-  "version": "6.0.0",
+  "version": "6.0.1",
   "type": "module",
   "description": "Zhin.js WeChat Official Account adapter for Plugin Runtime (HTTP webhook)",
   "main": "./lib/index.js",
@@ -8,18 +8,19 @@
   "dependencies": {
     "axios": "^1.19.0",
     "xml2js": "^0.6.2",
-    "@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": {
-    "@zhin.js/adapter": "1.2.0",
-    "@zhin.js/command": "1.0.15",
-    "@zhin.js/core": "1.5.13",
-    "@zhin.js/host-http": "1.0.12",
-    "zhin.js": "6.0.13"
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/command": "1.0.16",
+    "@zhin.js/core": "1.5.14",
+    "@zhin.js/host-http": "1.0.13",
+    "zhin.js": "6.0.14"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -34,7 +35,7 @@
     "@types/xml2js": "^0.4.14",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "zhin.js": "6.0.13"
+    "zhin.js": "6.0.14"
   },
   "keywords": [
     "zhin",

package/src/client.ts

@@ -0,0 +1,121 @@
+import type {
+  ResolvedWeChatMpConfig,
+  TokenResponse,
+  WeChatAPIResponse,
+} from './protocol.js';
+import type { WeChatMediaUploadResult } from './media-upload.js';
+import { defineEndpointClient } from 'zhin.js/adapter';
+
+const TOKEN_INVALID_ERRCODES = new Set([40001, 40014, 42001]);
+
+export type WeChatMpFetch = (
+  url: string,
+  init?: {
+    readonly method?: string;
+    readonly body?: unknown;
+    readonly headers?: Record<string, string>;
+  },
+) => Promise<{ readonly data: unknown }>;
+
+/** Direct WeChat Official Account API client exposed to plugins. */
+export class WeChatMpClient {
+  #accessToken: string | null = null;
+  #tokenExpireTime = 0;
+
+  constructor(
+    readonly config: ResolvedWeChatMpConfig,
+    readonly fetch: WeChatMpFetch,
+  ) {}
+
+  get accessToken(): string | null {
+    return this.#accessToken;
+  }
+
+  get tokenExpired(): boolean {
+    return !this.#accessToken || Date.now() >= this.#tokenExpireTime;
+  }
+
+  async refreshAccessToken(): Promise<string> {
+    const { appId, appSecret } = this.config;
+    const url = `https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=${appId}&secret=${appSecret}`;
+    const response = await this.fetch(url);
+    const data = response.data as TokenResponse & WeChatAPIResponse;
+    if (!data.access_token) {
+      throw new Error(data.errmsg
+        ? `Failed to get access token: ${data.errcode} ${data.errmsg}`
+        : 'Failed to get access token');
+    }
+    this.#accessToken = data.access_token;
+    this.#tokenExpireTime = Date.now() + (data.expires_in - 300) * 1000;
+    return data.access_token;
+  }
+
+  async request<T = unknown>(
+    path: string,
+    init?: Parameters<WeChatMpFetch>[1],
+  ): Promise<T> {
+    if (this.tokenExpired) await this.refreshAccessToken();
+    const separator = path.includes('?') ? '&' : '?';
+    const response = await this.fetch(
+      `https://api.weixin.qq.com${path}${separator}access_token=${this.#accessToken}`,
+      init,
+    );
+    return response.data as T;
+  }
+
+  async sendCustomerService(messageData: unknown): Promise<WeChatAPIResponse> {
+    let result = await this.request<WeChatAPIResponse>(
+      '/cgi-bin/message/custom/send',
+      { method: 'POST', body: messageData },
+    );
+    if (result.errcode && TOKEN_INVALID_ERRCODES.has(Number(result.errcode))) {
+      await this.refreshAccessToken();
+      result = await this.request<WeChatAPIResponse>(
+        '/cgi-bin/message/custom/send',
+        { method: 'POST', body: messageData },
+      );
+    }
+    return result;
+  }
+
+  async uploadMedia(
+    type: 'image' | 'voice' | 'video',
+    body: unknown,
+  ): Promise<string> {
+    const data = await this.request<WeChatMediaUploadResult>(
+      `/cgi-bin/media/upload?type=${type}`,
+      { method: 'POST', body },
+    );
+    if (data.media_id) return data.media_id;
+    throw new Error(`WeChat media upload failed: ${data.errcode ?? 'unknown'} ${data.errmsg ?? ''}`.trim());
+  }
+
+  async getFollowerIds(): Promise<readonly string[]> {
+    const followers: string[] = [];
+    let nextOpenid = '';
+    do {
+      const data = await this.request<WeChatAPIResponse & {
+        count?: number;
+        data?: { openid?: string[] };
+        next_openid?: string;
+      }>(`/cgi-bin/user/get?next_openid=${encodeURIComponent(nextOpenid)}`);
+      if (data.errcode && data.errcode !== 0) {
+        throw new Error(`WeChat API error: ${data.errcode} - ${data.errmsg}`);
+      }
+      followers.push(...(data.data?.openid ?? []).filter(Boolean));
+      if (Number(data.count ?? 0) < 10_000) break;
+      nextOpenid = data.next_openid ?? '';
+    } while (nextOpenid);
+    return Object.freeze(followers);
+  }
+}
+
+export type WeChatMpClientEventMap = Record<string, unknown>;
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly 'wechat-mp': { readonly client: WeChatMpClient; readonly events: WeChatMpClientEventMap };
+  }
+}
+
+export const wechatMpClient = defineEndpointClient<WeChatMpClient, WeChatMpClientEventMap>('wechat-mp');

package/src/endpoint.ts

@@ -1,9 +1,9 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
  * WeChatMpEndpoint — lifecycle, outbound, admit, access token refresh.
  */
 import axios from 'axios';
-import type { EndpointFriend, EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import type { EndpointManagement, 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';
@@ -14,8 +14,6 @@ import {
   formatInboundId,
   wechatMpInboundConversation,
   type ResolvedWeChatMpConfig,
-  type TokenResponse,
-  type WeChatAPIResponse,
   type WeChatMessage,
 } from './protocol.js';
 import {
@@ -30,9 +28,7 @@ import {
 } from './passive-reply.js';
 import { registerWeChatMpWebhookRoutes } from './webhook.js';
 import { receiveWeChatMpSideEvent } from './side-event-dispatch.js';
-
-/** token 失效类错误码：40001/40014 invalid access_token、42001 access_token expired。 */
-const TOKEN_INVALID_ERRCODES = new Set([40001, 40014, 42001]);
+import { WeChatMpClient, type WeChatMpFetch } from './client.js';
 
 /**
  * canonical 媒体段类型 → 微信 /cgi-bin/media/upload 的 type。
@@ -45,15 +41,8 @@ const WECHAT_UPLOAD_TYPE: Readonly<Record<string, 'image' | 'voice' | 'video'>>
   video: 'video',
 };
 
-export type WeChatMpFetch = (
-  url: string,
-  init?: { readonly method?: string; readonly body?: unknown; readonly headers?: Record<string, string> },
-) => Promise<{ readonly data: unknown }>;
-
 export interface WeChatMpEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: ResolvedWeChatMpConfig;
   readonly fetch?: WeChatMpFetch;
@@ -71,26 +60,27 @@ function defaultFetch(
   }).then((response) => ({ data: response.data }));
 }
 
-export class WeChatMpEndpoint implements EndpointInstance {
+export class WeChatMpEndpoint extends Endpoint<WeChatMpClient> {
+  readonly client: WeChatMpClient;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: WeChatMpEndpointOptions;
   readonly #fetch: WeChatMpFetch;
   #routeReleases: HttpRouteRegistration[] = [];
-  #accessToken: string | null = null;
-  #tokenExpireTime = 0;
   #tokenRefreshTimer?: ReturnType<typeof setInterval>;
   /** MsgId → 首次回复 XML（微信 5s 重推去重，有界 LRU）。 */
   readonly #replyCache = new Map<string, string>();
   static readonly #REPLY_CACHE_LIMIT = 1000;
   #open = false;
   #started = false;
-  readonly management: EndpointManagement = createWeChatMpEndpointManagement(this);
+  readonly management: EndpointManagement = createWeChatMpEndpointManagement(() => this.client);
 
   constructor(options: WeChatMpEndpointOptions) {
+    super();
     this.#logger = getAdapterLogger('wechat-mp', options.config.id);
     this.#options = options;
     this.#fetch = options.fetch ?? defaultFetch;
+    this.client = new WeChatMpClient(options.config, this.#fetch);
   }
 
   /** Used by webhook handler. */
@@ -106,10 +96,6 @@ export class WeChatMpEndpoint implements EndpointInstance {
     return this.#options.id;
   }
 
-  get gateway(): MessageGateway {
-    return this.#options.gateway;
-  }
-
   /** 微信 5s 重推去重：见过该 MsgId 时返回首次回复 XML（含空串=success）。 */
   getCachedReply(msgId: string): string | undefined {
     return this.#replyCache.get(msgId);
@@ -129,7 +115,7 @@ export class WeChatMpEndpoint implements EndpointInstance {
     if (this.#started) return;
     this.#started = true;
     try {
-      await this.#refreshAccessToken();
+      await this.client.refreshAccessToken();
       this.#routeReleases.push(...registerWeChatMpWebhookRoutes(this.#options.http, this));
       this.#startTokenRefreshTimer();
       this.#logger.debug(formatCompact({
@@ -184,18 +170,24 @@ export class WeChatMpEndpoint implements EndpointInstance {
   }
 
   /** Test / internal: admit a parsed message when open (non-webhook path). */
-  admit(msg: WeChatMessage): void {
+  admit(msg: WeChatMessage): void | Promise<unknown> {
     if (!this.#open) return;
+    void this.emitPlatform(msg.Event ? `${msg.MsgType}.${msg.Event}` : msg.MsgType, msg).catch((error) => {
+      this.#logger.warn(formatCompact({
+        op: 'wechat_mp_platform_event_failed',
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    });
     if (receiveWeChatMpSideEvent(
-      this.#options.sideEvents,
+      (name, payload) => this.emit(name, payload),
       this.#options.config.id,
       msg,
       this.#logger,
     )) {
-      return;
+      return undefined;
     }
     const conversation = wechatMpInboundConversation(String(this.#options.id), msg);
-    void this.#options.gateway.receive({
+    return this.emit('message.receive', {
       conversation,
       message: { conversation, id: formatInboundId(msg) },
       content: formatInboundContent(msg),
@@ -217,21 +209,9 @@ export class WeChatMpEndpoint implements EndpointInstance {
 
   async #sendCustomerService(target: string, payload: unknown): Promise<string> {
     // 发送前检查过期（不只判 null）：过期 token 直接刷新，不白跑一次 40001。
-    if (!this.#accessToken || Date.now() >= this.#tokenExpireTime) {
-      await this.#refreshAccessToken();
-    }
     const materialized = await this.#materializeOutboundMedia(payload);
     const messageData = formatCustomerServiceBody(target, materialized);
-    let result = await this.#postCustomerService(messageData);
-    if (result.errcode && TOKEN_INVALID_ERRCODES.has(Number(result.errcode))) {
-      // 对端提前作废 token（多端共用等）：刷新后重试一次。
-      this.#logger.warn(formatCompact({
-        op: 'wechat_mp_token_invalid_retry',
-        errcode: result.errcode,
-      }));
-      await this.#refreshAccessToken();
-      result = await this.#postCustomerService(messageData);
-    }
+    const result = await this.client.sendCustomerService(messageData);
     if (result.errcode && result.errcode !== 0) {
       throw new Error(`WeChat API error: ${result.errcode} - ${result.errmsg}`);
     }
@@ -305,76 +285,13 @@ export class WeChatMpEndpoint implements EndpointInstance {
   ): Promise<string> {
     const binary = await resolveMediaBinary(media);
     const form = buildMediaUploadForm(binary);
-    const url = `https://api.weixin.qq.com/cgi-bin/media/upload?access_token=${this.#accessToken}&type=${type}`;
-    const response = await this.#fetch(url, { method: 'POST', body: form });
-    const data = response.data as WeChatMediaUploadResult;
-    if (data.media_id) return data.media_id;
-    throw new Error(`WeChat media upload failed: ${data.errcode ?? 'unknown'} ${data.errmsg ?? ''}`.trim());
-  }
-
-  async #postCustomerService(messageData: unknown): Promise<WeChatAPIResponse> {
-    const url = `https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=${this.#accessToken}`;
-    const response = await this.#fetch(url, { method: 'POST', body: messageData });
-    return response.data as WeChatAPIResponse;
-  }
-
-  /**
-   * 关注者列表（GET /cgi-bin/user/get，按 next_openid 分页，每页最多 10000）。
-   * 该接口只回 openid 不回昵称；昵称需逐个调 user/info（成本高且依赖用户授权），
-   * 这里 nickname 用 openid 占位，由 Console 侧自行理解。
-   */
-  async getFollowers(): Promise<readonly EndpointFriend[]> {
-    if (!this.#accessToken || Date.now() >= this.#tokenExpireTime) {
-      await this.#refreshAccessToken();
-    }
-    const friends: EndpointFriend[] = [];
-    let nextOpenid = '';
-    do {
-      const url = `https://api.weixin.qq.com/cgi-bin/user/get?access_token=${this.#accessToken}&next_openid=${encodeURIComponent(nextOpenid)}`;
-      const response = await this.#fetch(url);
-      const data = response.data as WeChatAPIResponse & {
-        count?: number;
-        data?: { openid?: string[] };
-        next_openid?: string;
-      };
-      if (data.errcode && data.errcode !== 0) {
-        throw new Error(`WeChat API error: ${data.errcode} - ${data.errmsg}`);
-      }
-      for (const openid of data.data?.openid ?? []) {
-        if (typeof openid === 'string' && openid) {
-          friends.push({ user_id: openid, nickname: openid, remark: '' });
-        }
-      }
-      const fetched = Number(data.count ?? 0);
-      nextOpenid = typeof data.next_openid === 'string' ? data.next_openid : '';
-      // 满页（10000）才可能有下一页；不足一页即到底，避免依赖 next_openid 回显语义。
-      if (fetched < 10_000) break;
-    } while (nextOpenid);
-    return friends;
-  }
-
-  async #refreshAccessToken(): Promise<void> {
-    const { appId, appSecret } = this.#options.config;
-    const url = `https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=${appId}&secret=${appSecret}`;
-    const response = await this.#fetch(url);
-    const data = response.data as TokenResponse & WeChatAPIResponse;
-    if (data.access_token) {
-      this.#accessToken = data.access_token;
-      this.#tokenExpireTime = Date.now() + (data.expires_in - 300) * 1000;
-      this.#logger.debug(formatCompact({ op: 'token_refresh' }));
-      return;
-    }
-    throw new Error(
-      data.errmsg
-        ? `Failed to get access token: ${data.errcode} ${data.errmsg}`
-        : 'Failed to get access token',
-    );
+    return this.client.uploadMedia(type, form);
   }
 
   #startTokenRefreshTimer(): void {
     this.#tokenRefreshTimer = setInterval(() => {
-      if (Date.now() >= this.#tokenExpireTime) {
-        void this.#refreshAccessToken().catch((error) => {
+      if (this.client.tokenExpired) {
+        void this.client.refreshAccessToken().catch((error) => {
           this.#logger.error('Failed to refresh access token in timer:', error);
         });
       }
@@ -382,9 +299,15 @@ export class WeChatMpEndpoint implements EndpointInstance {
   }
 }
 
-function createWeChatMpEndpointManagement(endpoint: WeChatMpEndpoint): EndpointManagement {
+function createWeChatMpEndpointManagement(
+  requireClient: () => WeChatMpClient,
+): EndpointManagement {
   return Object.freeze<EndpointManagement>({
     // 公众号无群/频道概念；关注者即"好友"（nickname 为 openid 占位，见 getFollowers）。
-    listFriends: () => endpoint.getFollowers(),
+    listFriends: async () => (await requireClient().getFollowerIds()).map((openid) => ({
+      user_id: openid,
+      nickname: openid,
+      remark: '',
+    })),
   });
 }

package/src/index.ts

@@ -31,10 +31,16 @@ export {
   type PassiveReplyCapture,
 } from './passive-reply.js';
 
+export {
+  WeChatMpClient,
+  wechatMpClient,
+  type WeChatMpClientEventMap,
+  type WeChatMpFetch,
+} from './client.js';
+
 export {
   WeChatMpEndpoint,
   type WeChatMpEndpointOptions,
-  type WeChatMpFetch,
 } from './endpoint.js';
 
 export {

package/src/protocol.ts

@@ -337,7 +337,7 @@ export function formatInboundId(msg: WeChatMessage): string {
     .join(':');
 }
 
-/** Build inbound text for MessageGateway.receive. */
+/** Build inbound text for OutboundMessageService.receive. */
 export function formatInboundContent(msg: WeChatMessage): string {
   switch (msg.MsgType) {
     case 'text':

package/src/side-event-dispatch.ts

@@ -1,5 +1,5 @@
 import { buildNotice, 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 { formatInboundId, type WeChatMessage } from './protocol.js';
 
@@ -15,15 +15,15 @@ function mapWeChatMpEventParts(eventName: string): { scene_type: string; sub_typ
 }
 
 export function receiveWeChatMpSideEvent(
-  sideEvents: SideEventGateway | undefined,
+  emit: EndpointEventEmitter,
   configId: string,
   msg: WeChatMessage,
   logger: ReturnType<typeof getAdapterLogger>,
 ): boolean {
-  if (!sideEvents || msg.MsgType !== 'event') return false;
+  if (msg.MsgType !== 'event') return false;
   const eventName = msg.Event ?? 'unknown';
   const parts = mapWeChatMpEventParts(eventName);
-  void sideEvents.receiveNotice(buildNotice(msg, {
+  void emit('notice.receive', buildNotice(msg, {
     $id: `wechat-mp:${formatInboundId(msg)}`,
     $adapter: 'wechat-mp' as never,
     $endpoint: configId,

package/src/webhook.ts

@@ -2,7 +2,6 @@
  * WeChat MP webhook HTTP: URL verification + inbound message handling.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -36,8 +35,7 @@ export interface WeChatMpWebhookHandler {
   readonly config: ResolvedWeChatMpConfig;
   readonly isOpen: boolean;
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  admit(msg: WeChatMessage): void;
+  admit(msg: WeChatMessage): void | Promise<unknown>;
   /** MsgId 去重缓存（可选；实现见 WeChatMpEndpoint）。 */
   getCachedReply?(msgId: string): string | undefined;
   cacheReply?(msgId: string, replyXML: string): void;
@@ -221,18 +219,7 @@ export async function collectPassiveReply(
   const text = await runWithPassiveReplyCapture(async () => {
     const conversation = wechatMpInboundConversation(String(handler.id), wechatMsg);
     await Promise.race([
-      handler.gateway.receive({
-        conversation,
-        message: { conversation, id: formatInboundId(wechatMsg) },
-        content: formatInboundContent(wechatMsg),
-        sender: { id: wechatMsg.FromUserName },
-        endpointId: handler.config.id,
-        metadata: Object.freeze({
-          msgType: wechatMsg.MsgType,
-          event: wechatMsg.Event,
-          toUserName: wechatMsg.ToUserName,
-        }),
-      }),
+      Promise.resolve(handler.admit(wechatMsg)),
       new Promise<void>((resolve) => setTimeout(resolve, timeoutMs)),
     ]);
     return getPassiveReplyCapture()?.text ?? null;