@zhin.js/adapter-weixin-ilink 6.0.0 → 6.0.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @zhin.js/adapter-weixin-ilink
 
+## 6.0.2
+
+### Patch Changes
+
+- Updated dependencies [ba7e17a]
+- Updated dependencies [7108d0b]
+  - @zhin.js/core@1.5.15
+  - zhin.js@6.0.15
+
+## 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/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

@@ -9,7 +9,7 @@
 | 项 | weixin-ilink | wechat-mp |
 |---|---|---|
 | 账号类型 | 个人微信（ClawBot） | 微信公众号 |
-| 入站 | 长轮询 `getupdates` → `messageGatewayToken` | Webhook（`httpHostToken`） |
+| 入站 | 长轮询 `getupdates` → `Endpoint.emit(...)` | Webhook（`httpHostToken`） |
 | 登录 | 扫码 / 侧车凭证 / `botToken` | AppId/Secret/Token |
 | 群聊 | 不支持（仅私聊） | 支持 |
 
@@ -52,7 +52,7 @@ data/weixin-ilink/<bot-name>.json
 
 回复必须携带入站时缓存的 `context_token`（按 `endpointId + peerUserId`）。若用户久未发消息导致 token 缺失，出站会拒绝并打 warn。
 
-出站经 Runtime：`MessageGateway` → `endpoint.send({ conversation, payload })`（`conversation` 为入站归一化出的 `ConversationRef`，kind 恒为 `private`，`id` 即对端 user_id）。
+出站经 Runtime：`OutboundMessageService` → `endpoint.send({ conversation, payload })`（`conversation` 为入站归一化出的 `ConversationRef`，kind 恒为 `private`，`id` 即对端 user_id）。
 
 **图文限制**：微信单条消息不支持图文混排。适配器会自动：
 

package/adapters/weixin-ilink.js

@@ -3,7 +3,6 @@
  * Convention entry: discover `adapters/weixin-ilink.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { WeixinIlinkEndpoint } from "../lib/endpoint.js";
 import { resolveWeixinIlinkConfig, } from "../lib/protocol.js";
 import { weixinIlinkRuntimeStateToken } from "../lib/weixin-ilink-runtime-state.js";
@@ -27,8 +26,6 @@ export default defineAdapter({
         });
         return new WeixinIlinkEndpoint({
             id: context.id,
-            gateway: context.use(messageGatewayToken),
-            sideEvents: context.use(sideEventGatewayToken),
             config,
         });
     },

package/adapters/weixin-ilink.ts

@@ -2,7 +2,6 @@
  * Convention entry: discover `adapters/weixin-ilink.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { WeixinIlinkEndpoint } from '../src/endpoint.js';
 import {
   resolveWeixinIlinkConfig,
@@ -38,8 +37,6 @@ export default defineAdapter<WeixinIlinkAdapterConfig>({
     });
     return new WeixinIlinkEndpoint({
       id: context.id,
-      gateway: context.use(messageGatewayToken),
-      sideEvents: context.use(sideEventGatewayToken),
       config,
     });
   },

package/lib/client.d.ts

@@ -0,0 +1,34 @@
+import type { WeixinIlinkCredentials } from './credentials.js';
+import type { WeixinConfigManager } from './ilink-config-cache.js';
+import type { ResolvedWeixinIlinkConfig } from './protocol.js';
+import { sendMessageWeixin } from './weixin-send.js';
+/** Direct iLink API client backed by the Endpoint's live authenticated session. */
+export declare class WeixinIlinkClient {
+    readonly config: ResolvedWeixinIlinkConfig;
+    private readonly resolveCredentials;
+    private readonly resolveConfigManager;
+    private readonly sendTextImpl;
+    constructor(config: ResolvedWeixinIlinkConfig, resolveCredentials: () => WeixinIlinkCredentials | null, resolveConfigManager: () => WeixinConfigManager | undefined, sendTextImpl: typeof sendMessageWeixin);
+    get credentials(): WeixinIlinkCredentials;
+    get authenticated(): boolean;
+    get apiBaseUrl(): string;
+    get cdnBaseUrl(): string;
+    contextToken(userId: string): string | undefined;
+    sendText(to: string, text: string): Promise<{
+        messageId: string;
+    }>;
+    sendMedia(to: string, filePath: string, text?: string): Promise<{
+        messageId: string;
+    }>;
+    sendTyping(userId: string, status: number): Promise<boolean>;
+}
+export type WeixinIlinkClientEventMap = Record<string, unknown>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly 'weixin-ilink': {
+            readonly client: WeixinIlinkClient;
+            readonly events: WeixinIlinkClientEventMap;
+        };
+    }
+}
+export declare const weixinIlinkClient: import("@zhin.js/adapter").EndpointClientToken<WeixinIlinkClient, WeixinIlinkClientEventMap>;

package/lib/client.js

@@ -0,0 +1,72 @@
+import { getContextToken } from './context-store.js';
+import { sendTyping } from './ilink-api.js';
+import { sendWeixinMediaFile } from './weixin-send-media.js';
+import { defineEndpointClient } from 'zhin.js/adapter';
+/** Direct iLink API client backed by the Endpoint's live authenticated session. */
+export class WeixinIlinkClient {
+    config;
+    resolveCredentials;
+    resolveConfigManager;
+    sendTextImpl;
+    constructor(config, resolveCredentials, resolveConfigManager, sendTextImpl) {
+        this.config = config;
+        this.resolveCredentials = resolveCredentials;
+        this.resolveConfigManager = resolveConfigManager;
+        this.sendTextImpl = sendTextImpl;
+    }
+    get credentials() {
+        const credentials = this.resolveCredentials();
+        if (!credentials?.botToken)
+            throw new Error('weixin-ilink client not authenticated');
+        return credentials;
+    }
+    get authenticated() {
+        return Boolean(this.resolveCredentials()?.botToken);
+    }
+    get apiBaseUrl() {
+        return this.resolveCredentials()?.baseUrl ?? this.config.baseUrl;
+    }
+    get cdnBaseUrl() {
+        return this.config.cdnBaseUrl;
+    }
+    contextToken(userId) {
+        return getContextToken(this.config.id, userId);
+    }
+    async sendText(to, text) {
+        const contextToken = this.contextToken(to);
+        if (!contextToken)
+            throw new Error(`missing context_token for peer ${to}`);
+        return this.sendTextImpl({
+            to,
+            text,
+            opts: { baseUrl: this.apiBaseUrl, token: this.credentials.botToken, contextToken },
+        });
+    }
+    async sendMedia(to, filePath, text = '') {
+        const contextToken = this.contextToken(to);
+        if (!contextToken)
+            throw new Error(`missing context_token for peer ${to}`);
+        return sendWeixinMediaFile({
+            filePath,
+            to,
+            text,
+            opts: { baseUrl: this.apiBaseUrl, token: this.credentials.botToken, contextToken },
+            cdnBaseUrl: this.cdnBaseUrl,
+        });
+    }
+    async sendTyping(userId, status) {
+        const manager = this.resolveConfigManager();
+        if (!this.authenticated || !manager)
+            return false;
+        const cfg = await manager.getForUser(userId, this.contextToken(userId));
+        if (!cfg.typingTicket)
+            return false;
+        await sendTyping({
+            baseUrl: this.apiBaseUrl,
+            token: this.credentials.botToken,
+            body: { ilink_user_id: userId, typing_ticket: cfg.typingTicket, status },
+        });
+        return true;
+    }
+}
+export const weixinIlinkClient = defineEndpointClient('weixin-ilink');

package/lib/endpoint.d.ts

@@ -1,18 +1,17 @@
-import type { EndpointControl, EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import { Endpoint } from 'zhin.js/adapter';
+import type { EndpointControl, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
 import type { CapabilityId } from 'zhin.js';
 import { getUpdates, notifyStart, notifyStop } from './ilink-api.js';
 import { type WeixinIlinkCredentials } from './credentials.js';
 import { sendMessageWeixin } from './weixin-send.js';
 import { type ResolvedWeixinIlinkConfig, type WeixinMessageWithMedia } from './protocol.js';
+import { WeixinIlinkClient } from './client.js';
 export type WeixinIlinkSendText = typeof sendMessageWeixin;
 export type WeixinIlinkNotifyStart = typeof notifyStart;
 export type WeixinIlinkNotifyStop = typeof notifyStop;
 export type WeixinIlinkGetUpdates = typeof getUpdates;
 export interface WeixinIlinkEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly config: ResolvedWeixinIlinkConfig;
     readonly resolveCredentials?: (config: ResolvedWeixinIlinkConfig, signal?: AbortSignal) => Promise<WeixinIlinkCredentials>;
     /** Test / internal: override network side effects. */
@@ -21,16 +20,13 @@ export interface WeixinIlinkEndpointOptions {
     readonly getUpdates?: WeixinIlinkGetUpdates;
     readonly sendText?: WeixinIlinkSendText;
 }
-export declare class WeixinIlinkEndpoint implements EndpointInstance {
+export declare class WeixinIlinkEndpoint extends Endpoint<WeixinIlinkClient> {
     #private;
+    readonly client: WeixinIlinkClient;
     readonly management: EndpointManagement;
     readonly control: EndpointControl;
     constructor(options: WeixinIlinkEndpointOptions);
     get hasCredentials(): boolean;
-    /** Live endpoint 名（context token 按 account 名分桶，management 推导对端用）。 */
-    get configName(): string;
-    apiBaseUrl(): string;
-    cdnBaseUrl(): string;
     start(): Promise<void>;
     open(): void;
     close(): void;
@@ -38,5 +34,4 @@ export declare class WeixinIlinkEndpoint implements EndpointInstance {
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     /** Test / internal: admit a parsed message when the endpoint is open. */
     admit(msg: WeixinMessageWithMedia): void;
-    sendTypingToUser(userId: string, status: number): Promise<void>;
 }

package/lib/endpoint.js

@@ -1,3 +1,4 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
  * WeixinIlinkEndpoint — lifecycle, long-poll inbound, outbound send.
  */
@@ -5,20 +6,20 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
-import { getUpdates, notifyStart, notifyStop, sendTyping } from './ilink-api.js';
+import { getUpdates, notifyStart, notifyStop } from './ilink-api.js';
 import { configureIlinkMeta } from './ilink-meta.js';
 import { loadSyncBuf, resolveStateDir, saveSyncBuf, } from './credentials.js';
 import { resolveCredentials } from './login.js';
-import { getContextToken, listContextTokenUserIds, restoreContextTokens, setContextToken, flushContextTokenPersist, } from './context-store.js';
+import { listContextTokenUserIds, restoreContextTokens, setContextToken, flushContextTokenPersist, } from './context-store.js';
 import { WeixinConfigManager } from './ilink-config-cache.js';
 import { getRemainingPauseMs, isSessionPaused, pauseSession, SESSION_EXPIRED_ERRCODE, } from './ilink-session-guard.js';
 import { downloadMediaFromItem } from './media-download.js';
 import { sendMessageWeixin } from './weixin-send.js';
-import { sendWeixinMediaFile } from './weixin-send-media.js';
 import { materializeOutboundMedia } from './outbound-media.js';
 import { MessageItemType } from './ilink-types.js';
 import { getExtensionFromMime, sniffMimeFromBuffer } from './mime.js';
 import { formatInboundContent, weixinInboundSegments, weixinReplyTo, formatOutboundSegments, inboundMessageId, segmentLocalPath, sleep, weixinIlinkInboundConversation, } from './protocol.js';
+import { WeixinIlinkClient } from './client.js';
 const MAX_CONSECUTIVE_FAILURES = 3;
 const BACKOFF_DELAY_MS = 30_000;
 const RETRY_DELAY_MS = 2_000;
@@ -26,7 +27,8 @@ const WEIXIN_MEDIA_MAX_BYTES = 100 * 1024 * 1024;
 /** 入站媒体保留 24h，每小时清扫一次。 */
 const INBOUND_MEDIA_TTL_MS = 24 * 60 * 60 * 1000;
 const MEDIA_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
-export class WeixinIlinkEndpoint {
+export class WeixinIlinkEndpoint extends Endpoint {
+    client;
     #logger;
     #options;
     #resolveCredentials;
@@ -42,11 +44,14 @@ export class WeixinIlinkEndpoint {
     #mediaSweepTimer;
     #open = false;
     #started = false;
-    management = createWeixinIlinkEndpointManagement(this);
+    management = createWeixinIlinkEndpointManagement(() => this.client);
     control = Object.freeze({
-        typing: (conversation, active) => this.sendTypingToUser(conversation.id, active === false ? 2 : 1),
+        typing: async (conversation, active) => {
+            await this.client.sendTyping(conversation.id, active === false ? 2 : 1);
+        },
     });
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('weixin-ilink', options.config.id);
         this.#options = options;
         this.#resolveCredentials = options.resolveCredentials ?? resolveCredentials;
@@ -54,19 +59,10 @@ export class WeixinIlinkEndpoint {
         this.#notifyStop = options.notifyStop ?? notifyStop;
         this.#getUpdates = options.getUpdates ?? getUpdates;
         this.#sendText = options.sendText ?? sendMessageWeixin;
+        this.client = new WeixinIlinkClient(options.config, () => this.#creds, () => this.#configManager, this.#sendText);
     }
     get hasCredentials() {
-        return Boolean(this.#creds?.botToken);
-    }
-    /** Live endpoint 名（context token 按 account 名分桶，management 推导对端用）。 */
-    get configName() {
-        return this.#options.config.id;
-    }
-    apiBaseUrl() {
-        return this.#creds?.baseUrl ?? this.#options.config.baseUrl;
-    }
-    cdnBaseUrl() {
-        return this.#options.config.cdnBaseUrl;
+        return this.client.authenticated;
     }
     async start() {
         if (this.#started)
@@ -79,10 +75,10 @@ export class WeixinIlinkEndpoint {
             this.#creds = await this.#resolveCredentials(this.#options.config, this.#loginAbort.signal);
             restoreContextTokens(this.#options.config.id);
             await this.#notifyStart({
-                baseUrl: this.apiBaseUrl(),
+                baseUrl: this.client.apiBaseUrl,
                 token: this.#creds.botToken,
             });
-            this.#configManager = new WeixinConfigManager({ baseUrl: this.apiBaseUrl(), token: this.#creds.botToken }, (msg) => this.#logger.debug(msg));
+            this.#configManager = new WeixinConfigManager({ baseUrl: this.client.apiBaseUrl, token: this.#creds.botToken }, (msg) => this.#logger.debug(msg));
             this.#pollAbort = new AbortController();
             this.#pollPromise = this.#pollLoop(this.#pollAbort.signal);
             this.#startMediaSweep();
@@ -90,6 +86,9 @@ export class WeixinIlinkEndpoint {
                 op: 'connect',
                 endpoint: this.#options.config.id,
             }));
+            void this.#emitPlatformEvent('system.online', {
+                account: this.#options.config.id,
+            });
         }
         catch (error) {
             await this.stop();
@@ -118,7 +117,7 @@ export class WeixinIlinkEndpoint {
         flushContextTokenPersist(this.#options.config.id);
         if (this.#creds?.botToken) {
             try {
-                await this.#notifyStop({ baseUrl: this.apiBaseUrl(), token: this.#creds.botToken });
+                await this.#notifyStop({ baseUrl: this.client.apiBaseUrl, token: this.#creds.botToken });
             }
             catch (err) {
                 this.#logger.warn(formatCompact({
@@ -129,6 +128,9 @@ export class WeixinIlinkEndpoint {
             }
         }
         this.#started = false;
+        void this.#emitPlatformEvent('system.offline', {
+            account: this.#options.config.id,
+        });
         this.#logger.debug(formatCompact({
             op: 'disconnect',
         }));
@@ -139,7 +141,7 @@ export class WeixinIlinkEndpoint {
         }
         // 个人微信仅 private 会话，对端 user_id 即 conversation.id
         const target = conversation.id;
-        const contextToken = getContextToken(this.#options.config.id, target);
+        const contextToken = this.client.contextToken(target);
         if (!contextToken) {
             this.#logger.warn(formatCompact({
                 op: 'send',
@@ -149,11 +151,6 @@ export class WeixinIlinkEndpoint {
             }));
             throw new Error(`missing context_token for peer ${target}`);
         }
-        const apiOpts = {
-            baseUrl: this.apiBaseUrl(),
-            token: this.#creds.botToken,
-            contextToken,
-        };
         const outboundDir = path.join(resolveStateDir(), 'media', 'outbound');
         const wire = formatOutboundSegments(payload);
         const materialized = await materializeOutboundMedia(wire, outboundDir);
@@ -176,21 +173,11 @@ export class WeixinIlinkEndpoint {
             if (filePath && fs.existsSync(filePath)) {
                 // 微信限制：单条消息不能图文混排 → 先单独发文本，再发纯媒体
                 if (pendingText.trim()) {
-                    const textResult = await this.#sendText({
-                        to: target,
-                        text: pendingText,
-                        opts: apiOpts,
-                    });
+                    const textResult = await this.client.sendText(target, pendingText);
                     pendingText = '';
                     lastId = textResult.messageId;
                 }
-                const result = await sendWeixinMediaFile({
-                    filePath,
-                    to: target,
-                    text: '',
-                    opts: apiOpts,
-                    cdnBaseUrl: this.cdnBaseUrl(),
-                });
+                const result = await this.client.sendMedia(target, filePath);
                 lastId = result.messageId;
                 continue;
             }
@@ -203,11 +190,7 @@ export class WeixinIlinkEndpoint {
             }
         }
         if (pendingText.trim()) {
-            const result = await this.#sendText({
-                to: target,
-                text: pendingText,
-                opts: apiOpts,
-            });
+            const result = await this.client.sendText(target, pendingText);
             lastId = result.messageId;
         }
         return lastId || `weixin-ilink-${Date.now()}`;
@@ -222,7 +205,7 @@ export class WeixinIlinkEndpoint {
         }
         const conversation = weixinIlinkInboundConversation(String(this.#options.id), userId);
         const replyTo = weixinReplyTo(msg);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: inboundMessageId(msg) },
             content: formatInboundContent(msg),
@@ -242,29 +225,6 @@ export class WeixinIlinkEndpoint {
             }));
         });
     }
-    async sendTypingToUser(userId, status) {
-        if (!this.#creds?.botToken || !this.#configManager)
-            return;
-        const contextToken = getContextToken(this.#options.config.id, userId);
-        const cfg = await this.#configManager.getForUser(userId, contextToken);
-        if (!cfg.typingTicket) {
-            this.#logger.debug(formatCompact({
-                op: 'send_typing',
-                skip: 'no_typing_ticket',
-                userId,
-            }));
-            return;
-        }
-        await sendTyping({
-            baseUrl: this.apiBaseUrl(),
-            token: this.#creds.botToken,
-            body: {
-                ilink_user_id: userId,
-                typing_ticket: cfg.typingTicket,
-                status,
-            },
-        });
-    }
     async #pollLoop(abortSignal) {
         if (!this.#creds?.botToken)
             return;
@@ -279,7 +239,7 @@ export class WeixinIlinkEndpoint {
             }
             try {
                 const resp = await this.#getUpdates({
-                    baseUrl: this.apiBaseUrl(),
+                    baseUrl: this.client.apiBaseUrl,
                     token: this.#creds.botToken,
                     get_updates_buf: getUpdatesBuf,
                     timeoutMs: nextTimeoutMs,
@@ -338,6 +298,7 @@ export class WeixinIlinkEndpoint {
         }
     }
     async #handleInboundMessage(full) {
+        void this.#emitPlatformEvent(`message.${full.message_type ?? 'unknown'}`, full);
         const fromUserId = full.from_user_id ?? '';
         if (full.context_token && fromUserId) {
             setContextToken(this.#options.config.id, fromUserId, full.context_token);
@@ -351,6 +312,15 @@ export class WeixinIlinkEndpoint {
             preview: formatInboundContent({ ...full, _media: mediaOpts }).slice(0, 80),
         }));
     }
+    async #emitPlatformEvent(name, event) {
+        await this.emitPlatform(name, event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'weixin_ilink_platform_event_failed',
+                event: name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    }
     async #downloadInboundMedia(full) {
         const hasDownloadableMedia = (m) => Boolean(m?.encrypt_query_param || m?.full_url);
         const mediaItem = full.item_list?.find((i) => i.type === MessageItemType.IMAGE && hasDownloadableMedia(i.image_item?.media))
@@ -360,7 +330,7 @@ export class WeixinIlinkEndpoint {
         if (!mediaItem)
             return {};
         return downloadMediaFromItem(mediaItem, {
-            cdnBaseUrl: this.cdnBaseUrl(),
+            cdnBaseUrl: this.client.cdnBaseUrl,
             saveMedia: (buffer, contentType, subdir, maxBytes, originalFilename) => this.#saveInboundMedia(buffer, contentType, subdir, maxBytes, originalFilename),
             log: (msg) => this.#logger.debug(msg),
             errLog: (msg) => this.#logger.warn(msg),
@@ -432,13 +402,13 @@ export class WeixinIlinkEndpoint {
         }
     }
 }
-function createWeixinIlinkEndpointManagement(endpoint) {
+function createWeixinIlinkEndpointManagement(requireClient) {
     return Object.freeze({
         // 个人微信无群概念（listGroups/listGroupMembers 不接），也没有通讯录/资料接口。
         // "好友"只能从会话推导：凡持有 context_token 的对端（来过消息，含重启后从磁盘恢复的）
         // 即为可达私聊对端；昵称不可得，用 user_id 占位并在 remark 注明来源。
         async listFriends() {
-            return listContextTokenUserIds(endpoint.configName).map((userId) => ({
+            return listContextTokenUserIds(requireClient().config.id).map((userId) => ({
                 user_id: userId,
                 nickname: userId,
                 remark: 'ilink: 从会话 context_token 推导，非通讯录',

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 export { formatInboundContent, formatOutboundSegments, inboundMessageId, resolveWeixinIlinkConfig, segmentLocalPath, sleep, type ResolvedWeixinIlinkConfig, type WeixinIlinkAdapterConfig, type WeixinIlinkEndpointConfig, type WeixinInboundMediaPaths, type WeixinMessageWithMedia, type WeixinWireSegment, } from './protocol.js';
 export type { WeixinMessage, MessageItem } from './ilink-types.js';
 export type { WeixinIlinkCredentials } from './credentials.js';
+export { WeixinIlinkClient, weixinIlinkClient, type WeixinIlinkClientEventMap, } from './client.js';
 export { WeixinIlinkEndpoint, type WeixinIlinkEndpointOptions, type WeixinIlinkGetUpdates, type WeixinIlinkNotifyStart, type WeixinIlinkNotifyStop, type WeixinIlinkSendText, } from './endpoint.js';

package/lib/index.js

@@ -1,2 +1,3 @@
 export { formatInboundContent, formatOutboundSegments, inboundMessageId, resolveWeixinIlinkConfig, segmentLocalPath, sleep, } from './protocol.js';
+export { WeixinIlinkClient, weixinIlinkClient, } from './client.js';
 export { WeixinIlinkEndpoint, } from './endpoint.js';

package/lib/protocol.d.ts

@@ -41,7 +41,7 @@ export type WeixinMessageWithMedia = WeixinMessage & {
     readonly _media?: WeixinInboundMediaPaths;
 };
 export declare function resolveWeixinIlinkConfig(config?: WeixinIlinkAdapterConfig): ResolvedWeixinIlinkConfig;
-/** Build inbound text for MessageGateway.receive (gateway owns reply routing). */
+/** Build inbound text for OutboundMessageService.receive (gateway owns reply routing). */
 export declare function formatInboundContent(msg: WeixinMessageWithMedia): string;
 export declare function weixinInboundSegments(msg: WeixinMessageWithMedia): readonly Segment[];
 export declare function weixinReplyTo(msg: WeixinMessageWithMedia): Readonly<{

package/lib/protocol.js

@@ -28,7 +28,7 @@ export function resolveWeixinIlinkConfig(config = {}) {
         botToken,
     };
 }
-/** Build inbound text for MessageGateway.receive (gateway owns reply routing). */
+/** Build inbound text for OutboundMessageService.receive (gateway owns reply routing). */
 export function formatInboundContent(msg) {
     return bodyFromItemList(msg.item_list).trim();
 }

package/lib/weixin-ilink-endpoint-commands.d.ts

@@ -1 +1 @@
-export declare const weixinIlinkEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;
+export declare const weixinIlinkEndpointCommands: 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-weixin-ilink",
-  "version": "6.0.0",
+  "version": "6.0.2",
   "type": "module",
   "description": "Zhin.js Weixin iLink (ClawBot) adapter for Plugin Runtime (long-poll)",
   "main": "./lib/index.js",
@@ -48,16 +48,17 @@
     }
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.2.0",
-    "@zhin.js/core": "1.5.13",
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/core": "1.5.15",
+    "@zhin.js/feature-kit": "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": "6.0.13"
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/command": "1.0.16",
+    "@zhin.js/core": "1.5.15",
+    "zhin.js": "6.0.15"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -71,7 +72,7 @@
     "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "zhin.js": "6.0.13"
+    "zhin.js": "6.0.15"
   },
   "ilink_appid": "bot",
   "engines": {

package/src/client.ts

@@ -0,0 +1,85 @@
+import { getContextToken } from './context-store.js';
+import type { WeixinIlinkCredentials } from './credentials.js';
+import { sendTyping } from './ilink-api.js';
+import type { WeixinConfigManager } from './ilink-config-cache.js';
+import type { ResolvedWeixinIlinkConfig } from './protocol.js';
+import { sendMessageWeixin } from './weixin-send.js';
+import { sendWeixinMediaFile } from './weixin-send-media.js';
+import { defineEndpointClient } from 'zhin.js/adapter';
+
+/** Direct iLink API client backed by the Endpoint's live authenticated session. */
+export class WeixinIlinkClient {
+  constructor(
+    readonly config: ResolvedWeixinIlinkConfig,
+    private readonly resolveCredentials: () => WeixinIlinkCredentials | null,
+    private readonly resolveConfigManager: () => WeixinConfigManager | undefined,
+    private readonly sendTextImpl: typeof sendMessageWeixin,
+  ) {}
+
+  get credentials(): WeixinIlinkCredentials {
+    const credentials = this.resolveCredentials();
+    if (!credentials?.botToken) throw new Error('weixin-ilink client not authenticated');
+    return credentials;
+  }
+
+  get authenticated(): boolean {
+    return Boolean(this.resolveCredentials()?.botToken);
+  }
+
+  get apiBaseUrl(): string {
+    return this.resolveCredentials()?.baseUrl ?? this.config.baseUrl;
+  }
+
+  get cdnBaseUrl(): string {
+    return this.config.cdnBaseUrl;
+  }
+
+  contextToken(userId: string): string | undefined {
+    return getContextToken(this.config.id, userId);
+  }
+
+  async sendText(to: string, text: string): Promise<{ messageId: string }> {
+    const contextToken = this.contextToken(to);
+    if (!contextToken) throw new Error(`missing context_token for peer ${to}`);
+    return this.sendTextImpl({
+      to,
+      text,
+      opts: { baseUrl: this.apiBaseUrl, token: this.credentials.botToken, contextToken },
+    });
+  }
+
+  async sendMedia(to: string, filePath: string, text = ''): Promise<{ messageId: string }> {
+    const contextToken = this.contextToken(to);
+    if (!contextToken) throw new Error(`missing context_token for peer ${to}`);
+    return sendWeixinMediaFile({
+      filePath,
+      to,
+      text,
+      opts: { baseUrl: this.apiBaseUrl, token: this.credentials.botToken, contextToken },
+      cdnBaseUrl: this.cdnBaseUrl,
+    });
+  }
+
+  async sendTyping(userId: string, status: number): Promise<boolean> {
+    const manager = this.resolveConfigManager();
+    if (!this.authenticated || !manager) return false;
+    const cfg = await manager.getForUser(userId, this.contextToken(userId));
+    if (!cfg.typingTicket) return false;
+    await sendTyping({
+      baseUrl: this.apiBaseUrl,
+      token: this.credentials.botToken,
+      body: { ilink_user_id: userId, typing_ticket: cfg.typingTicket, status },
+    });
+    return true;
+  }
+}
+
+export type WeixinIlinkClientEventMap = Record<string, unknown>;
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly 'weixin-ilink': { readonly client: WeixinIlinkClient; readonly events: WeixinIlinkClientEventMap };
+  }
+}
+
+export const weixinIlinkClient = defineEndpointClient<WeixinIlinkClient, WeixinIlinkClientEventMap>('weixin-ilink');

package/src/endpoint.ts

@@ -1,3 +1,4 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
  * WeixinIlinkEndpoint — lifecycle, long-poll inbound, outbound send.
  */
@@ -7,14 +8,12 @@ import path from 'node:path';
 import type {
   EndpointFriend,
   EndpointControl,
-  EndpointInstance,
   EndpointManagement,
   EndpointSendRequest,
 } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
-import { getUpdates, notifyStart, notifyStop, sendTyping } from './ilink-api.js';
+import { getUpdates, notifyStart, notifyStop } from './ilink-api.js';
 import { configureIlinkMeta } from './ilink-meta.js';
 import {
   loadSyncBuf,
@@ -24,7 +23,6 @@ import {
 } from './credentials.js';
 import { resolveCredentials } from './login.js';
 import {
-  getContextToken,
   listContextTokenUserIds,
   restoreContextTokens,
   setContextToken,
@@ -39,7 +37,6 @@ import {
 } from './ilink-session-guard.js';
 import { downloadMediaFromItem } from './media-download.js';
 import { sendMessageWeixin } from './weixin-send.js';
-import { sendWeixinMediaFile } from './weixin-send-media.js';
 import { materializeOutboundMedia } from './outbound-media.js';
 import { MessageItemType, type WeixinMessage } from './ilink-types.js';
 import { getExtensionFromMime, sniffMimeFromBuffer } from './mime.js';
@@ -57,6 +54,7 @@ import {
   type WeixinMessageWithMedia,
   type WeixinWireSegment,
 } from './protocol.js';
+import { WeixinIlinkClient } from './client.js';
 
 const MAX_CONSECUTIVE_FAILURES = 3;
 const BACKOFF_DELAY_MS = 30_000;
@@ -73,8 +71,6 @@ export type WeixinIlinkGetUpdates = typeof getUpdates;
 
 export interface WeixinIlinkEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly config: ResolvedWeixinIlinkConfig;
   readonly resolveCredentials?: (
     config: ResolvedWeixinIlinkConfig,
@@ -87,7 +83,8 @@ export interface WeixinIlinkEndpointOptions {
   readonly sendText?: WeixinIlinkSendText;
 }
 
-export class WeixinIlinkEndpoint implements EndpointInstance {
+export class WeixinIlinkEndpoint extends Endpoint<WeixinIlinkClient> {
+  readonly client: WeixinIlinkClient;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: WeixinIlinkEndpointOptions;
@@ -107,15 +104,18 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
   #mediaSweepTimer?: ReturnType<typeof setInterval>;
   #open = false;
   #started = false;
-  readonly management: EndpointManagement = createWeixinIlinkEndpointManagement(this);
+  readonly management: EndpointManagement = createWeixinIlinkEndpointManagement(() => this.client);
   readonly control: EndpointControl = Object.freeze<EndpointControl>({
-    typing: (conversation, active) => this.sendTypingToUser(
-      conversation.id,
-      active === false ? 2 : 1,
-    ),
+    typing: async (conversation, active) => {
+      await this.client.sendTyping(
+        conversation.id,
+        active === false ? 2 : 1,
+      );
+    },
   });
 
   constructor(options: WeixinIlinkEndpointOptions) {
+    super();
     this.#logger = getAdapterLogger('weixin-ilink', options.config.id);
     this.#options = options;
     this.#resolveCredentials = options.resolveCredentials ?? resolveCredentials;
@@ -123,23 +123,16 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
     this.#notifyStop = options.notifyStop ?? notifyStop;
     this.#getUpdates = options.getUpdates ?? getUpdates;
     this.#sendText = options.sendText ?? sendMessageWeixin;
+    this.client = new WeixinIlinkClient(
+      options.config,
+      () => this.#creds,
+      () => this.#configManager,
+      this.#sendText,
+    );
   }
 
   get hasCredentials(): boolean {
-    return Boolean(this.#creds?.botToken);
-  }
-
-  /** Live endpoint 名（context token 按 account 名分桶，management 推导对端用）。 */
-  get configName(): string {
-    return this.#options.config.id;
-  }
-
-  apiBaseUrl(): string {
-    return this.#creds?.baseUrl ?? this.#options.config.baseUrl;
-  }
-
-  cdnBaseUrl(): string {
-    return this.#options.config.cdnBaseUrl;
+    return this.client.authenticated;
   }
 
   async start(): Promise<void> {
@@ -153,12 +146,12 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
       restoreContextTokens(this.#options.config.id);
 
       await this.#notifyStart({
-        baseUrl: this.apiBaseUrl(),
+        baseUrl: this.client.apiBaseUrl,
         token: this.#creds.botToken,
       });
 
       this.#configManager = new WeixinConfigManager(
-        { baseUrl: this.apiBaseUrl(), token: this.#creds.botToken },
+        { baseUrl: this.client.apiBaseUrl, token: this.#creds.botToken },
         (msg) => this.#logger.debug(msg),
       );
 
@@ -169,6 +162,9 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
         op: 'connect',
         endpoint: this.#options.config.id,
       }));
+      void this.#emitPlatformEvent('system.online', {
+        account: this.#options.config.id,
+      });
     } catch (error) {
       await this.stop();
       this.#logger.error('Failed to connect weixin-ilink bot:', error);
@@ -198,7 +194,7 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
     flushContextTokenPersist(this.#options.config.id);
     if (this.#creds?.botToken) {
       try {
-        await this.#notifyStop({ baseUrl: this.apiBaseUrl(), token: this.#creds.botToken });
+        await this.#notifyStop({ baseUrl: this.client.apiBaseUrl, token: this.#creds.botToken });
       } catch (err) {
         this.#logger.warn(formatCompact({
           op: 'notify_stop',
@@ -208,6 +204,9 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
       }
     }
     this.#started = false;
+    void this.#emitPlatformEvent('system.offline', {
+      account: this.#options.config.id,
+    });
     this.#logger.debug(formatCompact({
           op: 'disconnect',
     }));
@@ -219,7 +218,7 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
     }
     // 个人微信仅 private 会话，对端 user_id 即 conversation.id
     const target = conversation.id;
-    const contextToken = getContextToken(this.#options.config.id, target);
+    const contextToken = this.client.contextToken(target);
     if (!contextToken) {
       this.#logger.warn(formatCompact({
         op: 'send',
@@ -230,12 +229,6 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
       throw new Error(`missing context_token for peer ${target}`);
     }
 
-    const apiOpts = {
-      baseUrl: this.apiBaseUrl(),
-      token: this.#creds.botToken,
-      contextToken,
-    };
-
     const outboundDir = path.join(resolveStateDir(), 'media', 'outbound');
     const wire = formatOutboundSegments(payload);
     const materialized = await materializeOutboundMedia(wire, outboundDir);
@@ -259,21 +252,11 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
       if (filePath && fs.existsSync(filePath)) {
         // 微信限制：单条消息不能图文混排 → 先单独发文本，再发纯媒体
         if (pendingText.trim()) {
-          const textResult = await this.#sendText({
-            to: target,
-            text: pendingText,
-            opts: apiOpts,
-          });
+          const textResult = await this.client.sendText(target, pendingText);
           pendingText = '';
           lastId = textResult.messageId;
         }
-        const result = await sendWeixinMediaFile({
-          filePath,
-          to: target,
-          text: '',
-          opts: apiOpts,
-          cdnBaseUrl: this.cdnBaseUrl(),
-        });
+        const result = await this.client.sendMedia(target, filePath);
         lastId = result.messageId;
         continue;
       }
@@ -288,11 +271,7 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
     }
 
     if (pendingText.trim()) {
-      const result = await this.#sendText({
-        to: target,
-        text: pendingText,
-        opts: apiOpts,
-      });
+      const result = await this.client.sendText(target, pendingText);
       lastId = result.messageId;
     }
 
@@ -308,7 +287,7 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
     }
     const conversation = weixinIlinkInboundConversation(String(this.#options.id), userId);
     const replyTo = weixinReplyTo(msg);
-    void this.#options.gateway.receive({
+    void this.emit('message.receive', {
       conversation,
       message: { conversation, id: inboundMessageId(msg) },
       content: formatInboundContent(msg),
@@ -329,29 +308,6 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
     });
   }
 
-  async sendTypingToUser(userId: string, status: number): Promise<void> {
-    if (!this.#creds?.botToken || !this.#configManager) return;
-    const contextToken = getContextToken(this.#options.config.id, userId);
-    const cfg = await this.#configManager.getForUser(userId, contextToken);
-    if (!cfg.typingTicket) {
-      this.#logger.debug(formatCompact({
-        op: 'send_typing',
-        skip: 'no_typing_ticket',
-        userId,
-      }));
-      return;
-    }
-    await sendTyping({
-      baseUrl: this.apiBaseUrl(),
-      token: this.#creds.botToken,
-      body: {
-        ilink_user_id: userId,
-        typing_ticket: cfg.typingTicket,
-        status,
-      },
-    });
-  }
-
   async #pollLoop(abortSignal: AbortSignal): Promise<void> {
     if (!this.#creds?.botToken) return;
 
@@ -368,7 +324,7 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
 
       try {
         const resp = await this.#getUpdates({
-          baseUrl: this.apiBaseUrl(),
+          baseUrl: this.client.apiBaseUrl,
           token: this.#creds.botToken,
           get_updates_buf: getUpdatesBuf,
           timeoutMs: nextTimeoutMs,
@@ -430,6 +386,7 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
   }
 
   async #handleInboundMessage(full: WeixinMessage): Promise<void> {
+    void this.#emitPlatformEvent(`message.${full.message_type ?? 'unknown'}`, full);
     const fromUserId = full.from_user_id ?? '';
     if (full.context_token && fromUserId) {
       setContextToken(this.#options.config.id, fromUserId, full.context_token);
@@ -445,6 +402,16 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
     }));
   }
 
+  async #emitPlatformEvent(name: string, event: unknown): Promise<void> {
+    await this.emitPlatform(name, event).catch((error) => {
+      this.#logger.warn(formatCompact({
+        op: 'weixin_ilink_platform_event_failed',
+        event: name,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    });
+  }
+
   async #downloadInboundMedia(full: WeixinMessage): Promise<WeixinInboundMediaOpts> {
     const hasDownloadableMedia = (m?: { encrypt_query_param?: string; full_url?: string }) =>
       Boolean(m?.encrypt_query_param || m?.full_url);
@@ -466,7 +433,7 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
     if (!mediaItem) return {};
 
     return downloadMediaFromItem(mediaItem, {
-      cdnBaseUrl: this.cdnBaseUrl(),
+      cdnBaseUrl: this.client.cdnBaseUrl,
       saveMedia: (buffer, contentType, subdir, maxBytes, originalFilename) =>
         this.#saveInboundMedia(buffer, contentType, subdir, maxBytes, originalFilename),
       log: (msg) => this.#logger.debug(msg),
@@ -546,13 +513,15 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
   }
 }
 
-function createWeixinIlinkEndpointManagement(endpoint: WeixinIlinkEndpoint): EndpointManagement {
+function createWeixinIlinkEndpointManagement(
+  requireClient: () => WeixinIlinkClient,
+): EndpointManagement {
   return Object.freeze<EndpointManagement>({
     // 个人微信无群概念（listGroups/listGroupMembers 不接），也没有通讯录/资料接口。
     // "好友"只能从会话推导：凡持有 context_token 的对端（来过消息，含重启后从磁盘恢复的）
     // 即为可达私聊对端；昵称不可得，用 user_id 占位并在 remark 注明来源。
     async listFriends(): Promise<readonly EndpointFriend[]> {
-      return listContextTokenUserIds(endpoint.configName).map((userId) => ({
+      return listContextTokenUserIds(requireClient().config.id).map((userId) => ({
         user_id: userId,
         nickname: userId,
         remark: 'ilink: 从会话 context_token 推导，非通讯录',

package/src/index.ts

@@ -16,6 +16,12 @@ export {
 export type { WeixinMessage, MessageItem } from './ilink-types.js';
 export type { WeixinIlinkCredentials } from './credentials.js';
 
+export {
+  WeixinIlinkClient,
+  weixinIlinkClient,
+  type WeixinIlinkClientEventMap,
+} from './client.js';
+
 export {
   WeixinIlinkEndpoint,
   type WeixinIlinkEndpointOptions,

package/src/protocol.ts

@@ -82,7 +82,7 @@ export function resolveWeixinIlinkConfig(
   };
 }
 
-/** Build inbound text for MessageGateway.receive (gateway owns reply routing). */
+/** Build inbound text for OutboundMessageService.receive (gateway owns reply routing). */
 export function formatInboundContent(msg: WeixinMessageWithMedia): string {
   return bodyFromItemList(msg.item_list).trim();
 }