@zhin.js/adapter-wecom 1.1.18 → 1.1.19

package/lib/endpoint.js

@@ -1,317 +1,32 @@
-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 { 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 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;
-    constructor(options) {
-        super();
-        this.#logger = getAdapterLogger('wecom', options.config.id);
-        this.#options = options;
-        this.#fetch = options.fetch ?? globalThis.fetch;
-    }
-    /** Used by webhook handler. */
-    get isOpen() {
-        return this.#open;
-    }
-    get config() {
-        return this.#options.config;
-    }
-    async start() {
-        if (this.#started)
-            return;
-        this.#started = true;
-        try {
-            await this.#refreshAccessToken();
-            this.#routeReleases.push(...registerWecomWebhookRoutes(this.#options.http, this));
-            this.#logger.debug(formatCompact({
-                endpoint: this.#options.config.id,
-                op: 'webhook',
-                path: this.#options.config.webhookPath,
-            }));
-        }
-        catch (error) {
-            await this.stop();
-            this.#logger.error('Failed to connect WeCom endpoint:', error);
-            throw error;
-        }
-    }
-    open() {
-        this.#open = true;
-    }
-    close() {
-        this.#open = false;
-    }
-    async stop() {
-        this.#open = false;
-        for (const release of this.#routeReleases.splice(0))
-            release();
-        this.#started = false;
-        this.#logger.debug(formatCompact({ op: 'disconnect' }));
-    }
-    async send({ conversation, payload, locale }) {
-        const materialized = await this.#materializeOutboundMedia(payload);
-        const content = formatOutboundBody(materialized, locale);
-        const body = buildSendRequestBody(conversation.id, content, 
-        // Legacy field: historically written into agentid (preserved for cutover).
-        this.#options.config.agentSecret);
-        const data = await this.#request('/cgi-bin/message/send', {
-            method: 'POST',
-            body,
-        });
-        if (data.errcode !== 0) {
-            throw new Error(`Failed to send message: ${data.errmsg} (${data.errcode})`);
-        }
-        this.#logger.debug(formatCompact({ op: 'send', to: `${conversation.kind}:${conversation.id}`,
-        }));
-        return data.msgid || `${Date.now()}`;
-    }
-    async recallMessage(messageId) {
-        if (!messageId)
-            return;
-        await this.#request('/cgi-bin/message/recall', {
-            method: 'POST',
-            body: { msgid: messageId },
-        });
-    }
-    /**
-     * message/send 的 image 段只接受 media_id：canonical MediaRef 按 kind 投递——
-     * file（平台不透明引用）直用为 media_id；base64/本地路径/URL 先经
-     * /cgi-bin/media/upload 物化；上传失败降级为文本（alt 优先），不阻断发送。
-     * 无 canonical MediaRef 的媒体段 warn + 丢弃。
-     */
-    async #materializeOutboundMedia(payload) {
-        if (!Array.isArray(payload))
-            return payload;
-        const items = await Promise.all(payload.map(async (item) => {
-            if (typeof item === 'string' || !item || typeof item !== 'object')
-                return item;
-            const seg = item;
-            if (seg.type !== 'image')
-                return item;
-            const data = seg.data ?? {};
-            const media = readOutboundImageMedia(data);
-            if (!media) {
-                this.#logger.warn(formatCompact({
-                    op: 'wecom_outbound_media_dropped',
-                    endpoint: this.#options.config.id,
-                    type: 'image',
-                    reason: 'missing_media_ref',
-                }));
-                return null;
-            }
-            if (media.kind === 'file') {
-                return { type: 'image', data: { media_id: media.value } };
-            }
-            try {
-                const mediaId = await this.#uploadMedia('image', media);
-                return { type: 'image', data: { media_id: mediaId } };
-            }
-            catch (error) {
-                this.#logger.warn(formatCompact({
-                    op: 'wecom_media_upload_failed',
-                    endpoint: this.#options.config.id,
-                    error: error instanceof Error ? error.message : String(error),
-                }));
-                const alt = typeof data.alt === 'string' && data.alt ? data.alt : '[image]';
-                return { type: 'text', data: { text: alt } };
-            }
-        }));
-        return items.filter((item) => item !== null);
-    }
-    /** POST /cgi-bin/media/upload（临时素材，3 天有效），返回 media_id。 */
-    async #uploadMedia(type, media) {
-        await this.#ensureAccessToken();
-        const binary = await resolveMediaBinary(media);
-        const form = buildMediaUploadForm(binary);
-        const url = `${this.#options.config.apiBaseUrl}/cgi-bin/media/upload?access_token=${this.#accessToken.access_token}&type=${type}`;
-        const response = await this.#fetch(url, { method: 'POST', body: form });
-        const data = await response.json();
-        if (data.errcode === 0 && data.media_id)
-            return data.media_id;
-        throw new Error(`WeCom media upload failed: ${data.errmsg ?? 'unknown'} (${data.errcode ?? '?'})`);
-    }
-    /** Test / internal: admit a parsed message when open (non-webhook path). */
-    admit(msg) {
-        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((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.emit('message.receive', {
-            conversation,
-            message: { conversation, id: msg.MsgId || `${msg.CreateTime}` },
-            content: formatInboundContent(msg),
-            sender: { id: msg.FromUserName },
-            endpointId: this.#options.config.id,
-            metadata: Object.freeze({
-                msgType: msg.MsgType,
-                event: msg.Event,
-                chatType,
-                toUserName: msg.ToUserName,
-                agentId: msg.AgentID,
-            }),
-        }).catch((err) => {
-            this.#logger.warn(formatCompact({
-                op: 'wecom_gateway_receive_failed',
-                target: `${conversation.kind}:${conversation.id}`,
-                error: err instanceof Error ? err.message : String(err),
-            }));
-        });
-    }
-    async #getUserInfo(userId) {
-        try {
-            const data = await this.#request('/cgi-bin/user/get', {
-                params: { userid: userId },
-            });
-            if (data.errcode === 0)
-                return data;
-            throw new Error(`Failed to get user info: ${data.errmsg}`);
-        }
-        catch (error) {
-            this.#logger.error('Failed to get user info:', error);
-            return null;
-        }
-    }
-    async #getDepartmentUsers(deptId) {
-        try {
-            const data = await this.#request('/cgi-bin/user/simplelist', {
-                params: { department_id: deptId },
-            });
-            if (data.errcode === 0)
-                return data.userlist || [];
-            throw new Error(`Failed to get department users: ${data.errmsg}`);
-        }
-        catch (error) {
-            this.#logger.error('Failed to get department users:', error);
-            return [];
-        }
-    }
-    async #getDepartmentList(deptId = 1) {
-        try {
-            const data = await this.#request('/cgi-bin/department/list', {
-                params: { id: deptId },
-            });
-            if (data.errcode === 0)
-                return data.department || [];
-            throw new Error(`Failed to get department list: ${data.errmsg}`);
-        }
-        catch (error) {
-            this.#logger.error('Failed to get department list:', error);
-            return [];
-        }
-    }
-    async #sendTextMessage(userId, content) {
-        try {
-            const endpointKey = String(this.#options.id);
-            await this.send({
-                conversation: {
-                    endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
-                    kind: resolveChatType(userId),
-                    id: userId,
-                },
-                payload: content,
-            });
-            return true;
-        }
-        catch (error) {
-            this.#logger.error('Failed to send text message:', error);
-            return false;
-        }
-    }
-    async #request(path, options = {}) {
-        await this.#ensureAccessToken();
-        const { method = 'GET', params = {}, body } = options;
-        const urlParams = new URLSearchParams({
-            ...Object.fromEntries(Object.entries(params).map(([key, value]) => [key, String(value)])),
-            access_token: this.#accessToken.access_token,
-        });
-        const url = `${this.#options.config.apiBaseUrl}${path}?${urlParams.toString()}`;
-        const response = await this.#fetch(url, {
-            method,
-            headers: { 'Content-Type': 'application/json; charset=utf-8' },
-            body: body && method === 'POST' ? JSON.stringify(body) : undefined,
-        });
-        if (!response.ok) {
-            const text = await response.text().catch(() => '');
-            throw new Error(`WeCom API error ${response.status}: ${text}`);
-        }
-        return await response.json();
-    }
-    async #ensureAccessToken() {
-        const now = Date.now();
-        if (this.#accessToken.access_token
-            && now < this.#accessToken.timestamp + (this.#accessToken.expires_in - 300) * 1000) {
-            return;
-        }
-        if (this.#refreshPromise) {
-            await this.#refreshPromise;
-            return;
-        }
-        this.#refreshPromise = this.#refreshAccessToken()
-            .then(() => this.#accessToken.access_token)
-            .finally(() => { this.#refreshPromise = null; });
-        await this.#refreshPromise;
-    }
-    async #refreshAccessToken() {
-        const { corpId, agentSecret, apiBaseUrl } = this.#options.config;
-        const url = `${apiBaseUrl}/cgi-bin/gettoken?corpid=${corpId}&corpsecret=${agentSecret}`;
-        const response = await this.#fetch(url);
-        const data = await response.json();
-        if (data.errcode === 0 && data.access_token) {
-            this.#accessToken = {
-                access_token: data.access_token,
-                expires_in: data.expires_in ?? 7200,
-                timestamp: Date.now(),
-            };
-            this.#logger.debug('Access token refreshed successfully');
-            return;
-        }
-        throw new Error(`Failed to get access token: ${data.errmsg} (${data.errcode})`);
+import { createEndpointSpecification, endpointSpec } from 'zhin.js/adapter';
+import { WecomClient } from './client.js';
+/** Actual protocol Client; framework lifecycle and admission stay in their symbol namespace. */
+export class WecomEndpoint extends WecomClient {
+    [endpointSpec] = this.#createSpecification();
+    constructor(options) { super(options); }
+    #createSpecification() {
+        const hooks = {
+            start: (signal) => this.#startFramework(signal),
+            open: () => this.openInput(), close: () => this.closeInput(), stop: () => this.disconnectTransport(),
+            send: (request) => this.sendPayload(request),
+            name: this.configName(),
+            control: this.endpointControl,
+        };
+        Object.defineProperty(hooks, 'transportState', { get: () => this.transportState });
+        return createEndpointSpecification(this, hooks);
+    }
+    #startFramework(signal) { return this.connectTransport(signal); }
+    receiveInboundCallback(receive) {
+        return this[endpointSpec].events.run(receive);
+    }
+    publishEvent(name, payload) {
+        return this[endpointSpec].events.emit(name, payload);
+    }
+    publishAccepted(name, payload) {
+        return this[endpointSpec].events.emitAccepted(name, payload).then(() => undefined);
+    }
+    async publishPlatform(name, event) {
+        await super.publishPlatform(name, event);
+        return this[endpointSpec].events.platform(name, event);
     }
 }

package/lib/index.d.ts

@@ -1,6 +1,8 @@
 export { buildSendRequestBody, decryptMessage, extractEncryptFromXml, formatInboundContent, formatOutboundBody, getAesKey, normalizeEchostrParam, normalizeWebhookPath, parseXmlMessage, queryParam, readTextBody, resolveChatType, resolveWecomConfig, verifySignature, type AccessToken, type ResolvedWecomConfig, type WecomEndpointConfig, type WecomApiResponse, type WecomMessage, type WecomSendBody, type WecomWireSegment, } from './protocol.js';
-export { wecomClient, type WecomClientEventMap } from './client.js';
+export { type WecomClientEventMap } from './client.js';
 export { checkWecomPlatformPermit, normalizeWecomSenderForPermit, platformPermit, wecomGroupPermitResolver, } from './platform-permit.js';
-export { WecomClient, WecomEndpoint, type WecomClientApi, type WecomEndpointOptions, type WecomFetch, } from './endpoint.js';
+export { WecomEndpoint, 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';
+export { WecomClient, type WecomClientApi } from './client.js';
+export { WecomAdapter } from './adapter.js';

package/lib/index.js

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

package/lib/media-upload.d.ts

@@ -12,7 +12,11 @@ export interface WecomMediaUploadResult {
     readonly created_at?: string;
 }
 /** 从 canonical MediaRef 解析二进制：base64 解码 / 本地读盘 / URL 下载。 */
-export declare function resolveMediaBinary(media: MediaRef, download?: (url: string) => Promise<Buffer>): Promise<MediaBinary>;
+export interface MediaResolveOptions {
+    readonly download?: (url: string, signal?: AbortSignal) => Promise<Buffer>;
+    readonly signal?: AbortSignal;
+}
+export declare function resolveMediaBinary(media: MediaRef, { download, signal }?: MediaResolveOptions): Promise<MediaBinary>;
 /** 临时素材上传的 multipart body（字段名固定为 `media`）。 */
 export declare function buildMediaUploadForm(binary: MediaBinary): FormData;
 /**

package/lib/media-upload.js

@@ -13,8 +13,8 @@ const MIME_EXT = {
     'image/webp': 'webp',
     'image/bmp': 'bmp',
 };
-/** 从 canonical MediaRef 解析二进制：base64 解码 / 本地读盘 / URL 下载。 */
-export async function resolveMediaBinary(media, download = defaultDownload) {
+export async function resolveMediaBinary(media, { download = defaultDownload, signal } = {}) {
+    signal?.throwIfAborted();
     const mimeType = media.mime_type ?? 'image/png';
     const ext = MIME_EXT[mimeType] ?? 'png';
     if (media.kind === 'base64') {
@@ -25,16 +25,16 @@ export async function resolveMediaBinary(media, download = defaultDownload) {
     }
     if (media.kind === 'path') {
         const path = media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value;
-        return { data: await readFile(path), mimeType, fileName: basename(path) };
+        return { data: await readFile(path, { signal }), mimeType, fileName: basename(path) };
     }
     if (media.kind === 'url') {
-        return { data: await download(media.value), mimeType, fileName: `image.${ext}` };
+        return { data: await download(media.value, signal), mimeType, fileName: `image.${ext}` };
     }
     // kind=file 为平台不透明引用（media_id），无二进制可解，调用方应直用 value
     throw new Error(`cannot resolve binary from media kind: ${media.kind}`);
 }
-async function defaultDownload(url) {
-    const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+async function defaultDownload(url, signal) {
+    const response = await fetch(url, { signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000) });
     if (!response.ok)
         throw new Error(`download failed: HTTP ${response.status}`);
     return Buffer.from(await response.arrayBuffer());

package/lib/protocol.d.ts

@@ -5,6 +5,7 @@ import type { ConversationRef } from '@zhin.js/im-contract';
 export interface WecomEndpointConfig {
     readonly id: string;
     readonly corpId: string;
+    readonly agentId: string;
     readonly agentSecret: string;
     readonly token: string;
     readonly encodingAESKey: string;
@@ -15,6 +16,7 @@ export interface ResolvedWecomConfig {
     readonly context: 'wecom';
     readonly id: string;
     readonly corpId: string;
+    readonly agentId: string;
     readonly agentSecret: string;
     readonly token: string;
     readonly encodingAESKey: string;
@@ -22,6 +24,8 @@ export interface ResolvedWecomConfig {
     readonly apiBaseUrl: string;
 }
 export interface WecomMessage {
+    /** Complete decrypted callback XML; preserved before field projection. */
+    readonly rawXml?: string;
     readonly ToUserName: string;
     readonly FromUserName: string;
     readonly CreateTime: number;

package/lib/protocol.js

@@ -7,6 +7,7 @@ import { createHash, createDecipheriv, timingSafeEqual } from 'node:crypto';
 export function resolveWecomConfig(config) {
     const id = requiredEndpointField(config.id, 'id');
     const corpId = requiredEndpointField(config.corpId, 'corpId');
+    const agentId = requiredEndpointField(config.agentId, 'agentId');
     const agentSecret = requiredEndpointField(config.agentSecret, 'agentSecret');
     const token = requiredEndpointField(config.token, 'token');
     const encodingAESKey = requiredEndpointField(config.encodingAESKey, 'encodingAESKey');
@@ -14,6 +15,7 @@ export function resolveWecomConfig(config) {
         context: 'wecom',
         id,
         corpId,
+        agentId,
         agentSecret,
         token,
         encodingAESKey,
@@ -100,6 +102,7 @@ export function parseXmlMessage(xml) {
         if (!msgType)
             return null;
         const msg = {
+            rawXml: xml,
             ToUserName: get('ToUserName') || '',
             FromUserName: get('FromUserName') || '',
             CreateTime: Number(get('CreateTime') || Date.now()),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-wecom",
-  "version": "1.1.18",
+  "version": "1.1.19",
   "description": "Zhin.js WeCom (企业微信) adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,27 +33,27 @@
     "directory": "plugins/adapters/wecom"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.25",
-    "@zhin.js/agent-feature": "1.1.10",
-    "@zhin.js/client": "1.1.21",
+    "@zhin.js/adapter": "1.1.26",
+    "@zhin.js/agent-feature": "1.1.11",
+    "@zhin.js/client": "1.1.22",
     "@zhin.js/console-contract": "1.1.3",
-    "@zhin.js/core": "1.1.53",
-    "@zhin.js/feature-kit": "1.1.9",
-    "@zhin.js/host-http": "1.1.11",
+    "@zhin.js/core": "1.1.54",
+    "@zhin.js/feature-kit": "1.1.10",
+    "@zhin.js/host-http": "1.1.12",
     "@zhin.js/im-contract": "1.1.9",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/page": "1.1.10",
-    "@zhin.js/skill": "1.1.10",
-    "@zhin.js/tool": "1.1.12"
+    "@zhin.js/page": "1.1.11",
+    "@zhin.js/skill": "1.1.11",
+    "@zhin.js/tool": "1.1.13"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.25",
-    "@zhin.js/command": "^1.1.11",
-    "@zhin.js/core": "^1.1.53",
-    "@zhin.js/host-http": "^1.1.11",
-    "@zhin.js/permission": "^1.1.9",
-    "zhin.js": "^1.1.18"
+    "@zhin.js/adapter": "^1.1.26",
+    "@zhin.js/command": "^1.1.12",
+    "@zhin.js/core": "^1.1.54",
+    "@zhin.js/host-http": "^1.1.12",
+    "@zhin.js/permission": "^1.1.10",
+    "zhin.js": "^1.1.19"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -71,7 +71,7 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "zhin.js": "1.1.18"
+    "zhin.js": "1.1.19"
   },
   "files": [
     "adapters",
@@ -103,7 +103,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^1.0.0"
+        "api": "^2.0.0"
       },
       {
         "package": "@zhin.js/command",

package/plugin.js

@@ -1,9 +1,7 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { createEndpointRuntimeState } from 'zhin.js/adapter';
 import { definePlugin, pluginConsoleRpcToken } from 'zhin.js';
 import { permissionHostToken } from '@zhin.js/permission';
 import { checkWecomPlatformPermit } from "./lib/platform-permit.js";
-import { wecomRuntimeStateToken } from "./lib/wecom-runtime-state.js";
 import { createWecomConsoleRpc } from "./lib/console.js";
 export default definePlugin({
     name: 'wecom',
@@ -11,7 +9,6 @@ export default definePlugin({
         displayName: 'WeCom (企业微信) Adapter',
     },
     setup(context) {
-        context.resources.provide(wecomRuntimeStateToken, createEndpointRuntimeState());
         context.resources.provide(pluginConsoleRpcToken, createWecomConsoleRpc(context.resources, () => context.config.get()));
         if (context.resources.has(permissionHostToken)) {
             const host = context.resources.use(permissionHostToken);

package/schema.json

@@ -103,11 +103,22 @@
           "id": {
             "type": "string",
             "description": "WeCom bot name"
+          },
+          "agentId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "企业微信应用 AgentId（非应用 Secret）",
+            "x-i18n": {
+              "en": {
+                "description": "WeCom application AgentId (not the application secret)"
+              }
+            }
           }
         },
         "required": [
           "id",
           "corpId",
+          "agentId",
           "agentSecret",
           "token",
           "encodingAESKey"

package/src/adapter.ts

@@ -0,0 +1,30 @@
+import { WecomClient, type WecomClientEventMap } from './client.js';
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { WecomEndpoint } from './endpoint.js';
+import { resolveWecomConfig, type WecomEndpointConfig } from './protocol.js';
+import { httpHostToken } from '@zhin.js/host-http';
+
+export class WecomAdapter extends Adapter<WecomEndpoint, WecomEndpointConfig, WecomClientEventMap> {
+  readonly #context: AdapterContext<WecomEndpointConfig>;
+  constructor(context: AdapterContext<WecomEndpointConfig>) { super(); this.#context = context; }
+  override get configurationIdentityFields(): readonly string[] { return ['id', 'corpId', 'agentId']; }
+  override get configurationUpdateFields(): readonly string[] { return ['agentSecret', 'token', 'encodingAESKey', 'webhookPath', 'apiBaseUrl']; }
+  override get configurationIdentityProbeFields(): readonly string[] { return ['agentSecret', 'apiBaseUrl']; }
+  protected override async identifyConfiguration(input: WecomEndpointConfig, signal: AbortSignal, _changed: readonly string[]): Promise<string | undefined> {
+    const config = resolveWecomConfig(input);
+    const fetch = async (url: string, init?: Parameters<typeof globalThis.fetch>[1]) => { signal.throwIfAborted(); return globalThis.fetch(url, { ...init, signal }); };
+    const client = new WecomClient({ id: this.descriptor.id, config, fetch });
+    const response = await client.getApplicationInfo();
+    if (typeof response.agentid !== 'string' && typeof response.agentid !== 'number') throw new Error('WeCom identity verification returned no agentid');
+    return JSON.stringify(['wecom', new URL(config.apiBaseUrl).origin, config.corpId, String(response.agentid)]);
+  }
+  protected override validateConfiguration(config: WecomEndpointConfig): void { resolveWecomConfig(config); }
+  protected createEndpoint(input: WecomEndpointConfig, execution: EndpointCreationContext): WecomEndpoint {
+    const config = resolveWecomConfig(input);
+    return new WecomEndpoint({ id: execution.canonicalId, config, http: this.#context.use(httpHostToken) });
+  }
+}
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterRegistry { readonly 'wecom': WecomAdapter; }
+}