@zhin.js/adapter-weixin-ilink 5.0.1 → 5.0.4

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @zhin.js/adapter-weixin-ilink
 
+## 5.0.4
+
+### Patch Changes
+
+- Updated dependencies [c106ecc]
+- Updated dependencies [ca92e03]
+- Updated dependencies [b0f37ae]
+- Updated dependencies [ba08a2f]
+- Updated dependencies [daffd4c]
+- Updated dependencies [36c7400]
+- Updated dependencies [162fa34]
+- Updated dependencies [e40b048]
+- Updated dependencies [f1708c3]
+- Updated dependencies [e53444f]
+- Updated dependencies [92b0dd7]
+- Updated dependencies [a7df753]
+  - @zhin.js/im-contract@1.0.3
+  - @zhin.js/adapter@1.1.7
+  - @zhin.js/plugin-runtime@1.1.5
+  - @zhin.js/command@1.0.9
+  - @zhin.js/core@1.5.4
+  - zhin.js@6.0.4
+
+## 5.0.3
+
+### Patch Changes
+
+- f8c7a54: fix: im
+- Updated dependencies [f8c7a54]
+  - @zhin.js/logger@1.0.76
+  - @zhin.js/adapter@1.1.6
+  - @zhin.js/command@1.0.8
+  - @zhin.js/core@1.5.3
+  - @zhin.js/im-contract@1.0.2
+  - @zhin.js/plugin-runtime@1.1.4
+  - zhin.js@6.0.3
+
+## 5.0.2
+
+### Patch Changes
+
+- Updated dependencies [afc0e66]
+- Updated dependencies [2e41ad5]
+- Updated dependencies [9f57124]
+  - @zhin.js/core@1.5.2
+  - @zhin.js/adapter@1.1.5
+  - @zhin.js/im-contract@1.0.1
+  - @zhin.js/plugin-runtime@1.1.3
+  - @zhin.js/command@1.0.7
+  - zhin.js@6.0.2
+
 ## 5.0.1
 
 ### Patch Changes

package/README.md

@@ -52,7 +52,7 @@ data/weixin-ilink/<bot-name>.json
 
 回复必须携带入站时缓存的 `context_token`（按 `endpointId + peerUserId`）。若用户久未发消息导致 token 缺失，出站会拒绝并打 warn。
 
-出站经 Runtime：`MessageGateway` → `endpoint.send({ target, payload })`。
+出站经 Runtime：`MessageGateway` → `endpoint.send({ conversation, payload })`（`conversation` 为入站归一化出的 `ConversationRef`，kind 恒为 `private`，`id` 即对端 user_id）。
 
 **图文限制**：微信单条消息不支持图文混排。适配器会自动：
 
@@ -71,4 +71,3 @@ data/weixin-ilink/<bot-name>.json
 ## 文档
 
 - 适配器索引：[`plugins/adapters/README.md`](../README.md)
-- 原位迁移：[`docs/architecture/target-implementation/in-place-migration.md`](../../../docs/architecture/target-implementation/in-place-migration.md)

package/adapters/weixin-ilink.js

@@ -19,9 +19,10 @@ export default defineAdapter({
     create(context) {
         const config = resolveWeixinIlinkConfig(context.config);
         // 注册到插件运行时状态（weixin-ilink.endpoint list 的"运行中"数据源）
-        context.use(weixinIlinkRuntimeStateToken).endpoints.set(config.name, {
-            name: config.name,
-            mode: config.connection,
+        context.use(weixinIlinkRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
+            // iLink 仅长轮询一种接入方式，无 config.connection 字段
+            mode: 'long-poll',
         });
         return new WeixinIlinkEndpoint({
             id: context.id,

package/adapters/weixin-ilink.ts

@@ -30,9 +30,10 @@ export default defineAdapter<WeixinIlinkAdapterConfig>({
   create(context) {
     const config = resolveWeixinIlinkConfig(context.config);
     // 注册到插件运行时状态（weixin-ilink.endpoint list 的"运行中"数据源）
-    context.use(weixinIlinkRuntimeStateToken).endpoints.set(config.name, {
-      name: config.name,
-      mode: config.connection,
+    context.use(weixinIlinkRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
+      // iLink 仅长轮询一种接入方式，无 config.connection 字段
+      mode: 'long-poll',
     });
     return new WeixinIlinkEndpoint({
       id: context.id,

package/lib/credentials.d.ts

@@ -6,9 +6,9 @@ export interface WeixinIlinkCredentials {
     updatedAt?: string;
 }
 export declare function resolveStateDir(): string;
-export declare function credentialsPath(endpointName: string): string;
-export declare function loadCredentials(endpointName: string): WeixinIlinkCredentials | null;
-export declare function saveCredentials(endpointName: string, creds: WeixinIlinkCredentials): void;
-export declare function syncBufPath(endpointName: string): string;
-export declare function loadSyncBuf(endpointName: string): string;
-export declare function saveSyncBuf(endpointName: string, buf: string): void;
+export declare function credentialsPath(endpointId: string): string;
+export declare function loadCredentials(endpointId: string): WeixinIlinkCredentials | null;
+export declare function saveCredentials(endpointId: string, creds: WeixinIlinkCredentials): void;
+export declare function syncBufPath(endpointId: string): string;
+export declare function loadSyncBuf(endpointId: string): string;
+export declare function saveSyncBuf(endpointId: string, buf: string): void;

package/lib/credentials.js

@@ -6,11 +6,11 @@ export function resolveStateDir() {
         ? path.join(process.env.ZHIN_DATA_DIR, "weixin-ilink")
         : DEFAULT_DATA_DIR;
 }
-export function credentialsPath(endpointName) {
-    return path.join(resolveStateDir(), `${endpointName}.json`);
+export function credentialsPath(endpointId) {
+    return path.join(resolveStateDir(), `${endpointId}.json`);
 }
-export function loadCredentials(endpointName) {
-    const file = credentialsPath(endpointName);
+export function loadCredentials(endpointId) {
+    const file = credentialsPath(endpointId);
     try {
         if (!fs.existsSync(file))
             return null;
@@ -24,16 +24,16 @@ export function loadCredentials(endpointName) {
         return null;
     }
 }
-export function saveCredentials(endpointName, creds) {
-    const file = credentialsPath(endpointName);
+export function saveCredentials(endpointId, creds) {
+    const file = credentialsPath(endpointId);
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, JSON.stringify({ ...creds, updatedAt: new Date().toISOString() }, null, 2), "utf-8");
 }
-export function syncBufPath(endpointName) {
-    return path.join(resolveStateDir(), `${endpointName}.sync-buf`);
+export function syncBufPath(endpointId) {
+    return path.join(resolveStateDir(), `${endpointId}.sync-buf`);
 }
-export function loadSyncBuf(endpointName) {
-    const file = syncBufPath(endpointName);
+export function loadSyncBuf(endpointId) {
+    const file = syncBufPath(endpointId);
     try {
         return fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : "";
     }
@@ -41,8 +41,8 @@ export function loadSyncBuf(endpointName) {
         return "";
     }
 }
-export function saveSyncBuf(endpointName, buf) {
-    const file = syncBufPath(endpointName);
+export function saveSyncBuf(endpointId, buf) {
+    const file = syncBufPath(endpointId);
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, buf, "utf-8");
 }

package/lib/endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { getUpdates, notifyStart, notifyStop } from './ilink-api.js';
@@ -33,10 +33,7 @@ export declare class WeixinIlinkEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    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

@@ -4,7 +4,7 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { formatCompact, getLogger } from '@zhin.js/logger';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { getUpdates, notifyStart, notifyStop, sendTyping } from './ilink-api.js';
 import { configureIlinkMeta } from './ilink-meta.js';
 import { loadSyncBuf, resolveStateDir, saveSyncBuf, } from './credentials.js';
@@ -18,8 +18,7 @@ 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, formatOutboundSegments, inboundMessageId, segmentLocalPath, sleep, } from './protocol.js';
-const logger = getLogger('weixin-ilink');
+import { formatInboundContent, formatOutboundSegments, inboundMessageId, segmentLocalPath, sleep, weixinIlinkInboundConversation, } from './protocol.js';
 const MAX_CONSECUTIVE_FAILURES = 3;
 const BACKOFF_DELAY_MS = 30_000;
 const RETRY_DELAY_MS = 2_000;
@@ -28,6 +27,7 @@ const WEIXIN_MEDIA_MAX_BYTES = 100 * 1024 * 1024;
 const INBOUND_MEDIA_TTL_MS = 24 * 60 * 60 * 1000;
 const MEDIA_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
 export class WeixinIlinkEndpoint {
+    #logger;
     #options;
     #resolveCredentials;
     #notifyStart;
@@ -44,6 +44,7 @@ export class WeixinIlinkEndpoint {
     #started = false;
     management = createWeixinIlinkEndpointManagement(this);
     constructor(options) {
+        this.#logger = getAdapterLogger('weixin-ilink', options.config.id);
         this.#options = options;
         this.#resolveCredentials = options.resolveCredentials ?? resolveCredentials;
         this.#notifyStart = options.notifyStart ?? notifyStart;
@@ -56,7 +57,7 @@ export class WeixinIlinkEndpoint {
     }
     /** Live endpoint 名（context token 按 account 名分桶，management 推导对端用）。 */
     get configName() {
-        return this.#options.config.name;
+        return this.#options.config.id;
     }
     apiBaseUrl() {
         return this.#creds?.baseUrl ?? this.#options.config.baseUrl;
@@ -73,23 +74,23 @@ export class WeixinIlinkEndpoint {
             // QR 登录最长 8 分钟：stop() 必须能打断
             this.#loginAbort = new AbortController();
             this.#creds = await this.#resolveCredentials(this.#options.config, this.#loginAbort.signal);
-            restoreContextTokens(this.#options.config.name);
+            restoreContextTokens(this.#options.config.id);
             await this.#notifyStart({
                 baseUrl: this.apiBaseUrl(),
                 token: this.#creds.botToken,
             });
-            this.#configManager = new WeixinConfigManager({ baseUrl: this.apiBaseUrl(), token: this.#creds.botToken }, (msg) => logger.debug(msg));
+            this.#configManager = new WeixinConfigManager({ baseUrl: this.apiBaseUrl(), token: this.#creds.botToken }, (msg) => this.#logger.debug(msg));
             this.#pollAbort = new AbortController();
             this.#pollPromise = this.#pollLoop(this.#pollAbort.signal);
             this.#startMediaSweep();
-            logger.info(formatCompact({
+            this.#logger.info(formatCompact({
                 op: 'connect',
-                endpoint: this.#options.config.name,
+                endpoint: this.#options.config.id,
             }));
         }
         catch (error) {
             await this.stop();
-            logger.error('Failed to connect weixin-ilink bot:', error);
+            this.#logger.error('Failed to connect weixin-ilink bot:', error);
             throw error;
         }
     }
@@ -111,13 +112,13 @@ export class WeixinIlinkEndpoint {
         }
         this.#stopMediaSweep();
         // 防抖中的 context token 落盘，避免 stop 丢尾部写入
-        flushContextTokenPersist(this.#options.config.name);
+        flushContextTokenPersist(this.#options.config.id);
         if (this.#creds?.botToken) {
             try {
                 await this.#notifyStop({ baseUrl: this.apiBaseUrl(), token: this.#creds.botToken });
             }
             catch (err) {
-                logger.warn(formatCompact({
+                this.#logger.warn(formatCompact({
                     op: 'notify_stop',
                     ok: false,
                     error: err instanceof Error ? err.message : String(err),
@@ -125,18 +126,19 @@ export class WeixinIlinkEndpoint {
             }
         }
         this.#started = false;
-        logger.debug(formatCompact({
+        this.#logger.debug(formatCompact({
             op: 'disconnect',
-            endpoint: this.#options.config.name,
         }));
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         if (!this.#creds?.botToken) {
             throw new Error('weixin-ilink bot not authenticated');
         }
-        const contextToken = getContextToken(this.#options.config.name, target);
+        // 个人微信仅 private 会话，对端 user_id 即 conversation.id
+        const target = conversation.id;
+        const contextToken = getContextToken(this.#options.config.id, target);
         if (!contextToken) {
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'send',
                 ok: false,
                 reason: 'missing_context_token',
@@ -190,7 +192,7 @@ export class WeixinIlinkEndpoint {
                 continue;
             }
             if (seg.type === 'image' || seg.type === 'video' || seg.type === 'file' || seg.type === 'record') {
-                logger.warn(formatCompact({
+                this.#logger.warn(formatCompact({
                     op: 'send',
                     skip: 'no_local_file',
                     type: seg.type,
@@ -213,21 +215,21 @@ export class WeixinIlinkEndpoint {
             return;
         const userId = msg.from_user_id ?? '';
         if (msg.context_token && userId) {
-            setContextToken(this.#options.config.name, userId, msg.context_token);
+            setContextToken(this.#options.config.id, userId, msg.context_token);
         }
+        const conversation = weixinIlinkInboundConversation(String(this.#options.id), userId);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: userId,
+            conversation,
+            message: { conversation, id: inboundMessageId(msg) },
             content: formatInboundContent(msg),
-            sender: userId,
-            id: inboundMessageId(msg),
+            sender: { id: userId },
+            endpointId: this.#options.config.id,
             metadata: Object.freeze({
-                endpoint: this.#options.config.name,
                 messageType: msg.message_type,
                 createTimeMs: msg.create_time_ms,
             }),
         }).catch((err) => {
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'weixin_ilink_gateway_receive_failed',
                 target: userId,
                 error: err instanceof Error ? err.message : String(err),
@@ -237,10 +239,10 @@ export class WeixinIlinkEndpoint {
     async sendTypingToUser(userId, status) {
         if (!this.#creds?.botToken || !this.#configManager)
             return;
-        const contextToken = getContextToken(this.#options.config.name, userId);
+        const contextToken = getContextToken(this.#options.config.id, userId);
         const cfg = await this.#configManager.getForUser(userId, contextToken);
         if (!cfg.typingTicket) {
-            logger.debug(formatCompact({
+            this.#logger.debug(formatCompact({
                 op: 'send_typing',
                 skip: 'no_typing_ticket',
                 userId,
@@ -260,13 +262,13 @@ export class WeixinIlinkEndpoint {
     async #pollLoop(abortSignal) {
         if (!this.#creds?.botToken)
             return;
-        const endpointName = this.#options.config.name;
-        let getUpdatesBuf = loadSyncBuf(endpointName);
+        const endpointId = this.#options.config.id;
+        let getUpdatesBuf = loadSyncBuf(endpointId);
         let nextTimeoutMs = this.#options.config.longPollTimeoutMs;
         let consecutiveFailures = 0;
         while (!abortSignal.aborted) {
-            if (isSessionPaused(endpointName)) {
-                await sleep(getRemainingPauseMs(endpointName), abortSignal);
+            if (isSessionPaused(endpointId)) {
+                await sleep(getRemainingPauseMs(endpointId), abortSignal);
                 continue;
             }
             try {
@@ -285,9 +287,9 @@ export class WeixinIlinkEndpoint {
                 if (isApiError) {
                     const sessionExpired = resp.errcode === SESSION_EXPIRED_ERRCODE || resp.ret === SESSION_EXPIRED_ERRCODE;
                     if (sessionExpired) {
-                        pauseSession(endpointName);
+                        pauseSession(endpointId);
                         consecutiveFailures = 0;
-                        await sleep(getRemainingPauseMs(endpointName), abortSignal);
+                        await sleep(getRemainingPauseMs(endpointId), abortSignal);
                         continue;
                     }
                     consecutiveFailures += 1;
@@ -308,14 +310,14 @@ export class WeixinIlinkEndpoint {
                 }
                 if (nextBuf) {
                     getUpdatesBuf = nextBuf;
-                    saveSyncBuf(endpointName, getUpdatesBuf);
+                    saveSyncBuf(endpointId, getUpdatesBuf);
                 }
             }
             catch (err) {
                 if (abortSignal.aborted)
                     return;
                 consecutiveFailures += 1;
-                logger.error(formatCompact({
+                this.#logger.error(formatCompact({
                     op: 'poll',
                     ok: false,
                     error: err instanceof Error ? err.message : String(err),
@@ -332,13 +334,13 @@ export class WeixinIlinkEndpoint {
     async #handleInboundMessage(full) {
         const fromUserId = full.from_user_id ?? '';
         if (full.context_token && fromUserId) {
-            setContextToken(this.#options.config.name, fromUserId, full.context_token);
+            setContextToken(this.#options.config.id, fromUserId, full.context_token);
         }
         const mediaOpts = await this.#downloadInboundMedia(full);
         this.admit({ ...full, _media: mediaOpts });
-        logger.debug(formatCompact({
+        this.#logger.debug(formatCompact({
             op: 'recv',
-            endpoint: this.#options.config.name,
+            endpoint: this.#options.config.id,
             target: fromUserId,
             preview: formatInboundContent({ ...full, _media: mediaOpts }).slice(0, 80),
         }));
@@ -354,8 +356,8 @@ export class WeixinIlinkEndpoint {
         return downloadMediaFromItem(mediaItem, {
             cdnBaseUrl: this.cdnBaseUrl(),
             saveMedia: (buffer, contentType, subdir, maxBytes, originalFilename) => this.#saveInboundMedia(buffer, contentType, subdir, maxBytes, originalFilename),
-            log: (msg) => logger.debug(msg),
-            errLog: (msg) => logger.warn(msg),
+            log: (msg) => this.#logger.debug(msg),
+            errLog: (msg) => this.#logger.warn(msg),
             label: `inbound:${full.from_user_id ?? 'unknown'}`,
         });
     }
@@ -412,9 +414,9 @@ export class WeixinIlinkEndpoint {
                 if (now - stat.mtimeMs <= INBOUND_MEDIA_TTL_MS)
                     continue;
                 fs.unlinkSync(filePath);
-                logger.debug(formatCompact({
+                this.#logger.debug(formatCompact({
                     op: 'media_sweep',
-                    endpoint: this.#options.config.name,
+                    endpoint: this.#options.config.id,
                     file: entry.name,
                 }));
             }

package/lib/login.js

@@ -67,7 +67,7 @@ function sleepWithAbort(ms, signal) {
 export async function resolveCredentials(config, signal) {
     const envToken = process.env.WEIXIN_ILINK_TOKEN?.trim() || config.botToken?.trim();
     if (envToken) {
-        const stored = loadCredentials(config.name);
+        const stored = loadCredentials(config.id);
         return {
             botToken: envToken,
             ilinkUserId: stored?.ilinkUserId,
@@ -75,7 +75,7 @@ export async function resolveCredentials(config, signal) {
             baseUrl: config.baseUrl ?? stored?.baseUrl ?? DEFAULT_API_BASE_URL,
         };
     }
-    const stored = loadCredentials(config.name);
+    const stored = loadCredentials(config.id);
     if (stored?.botToken) {
         return {
             ...stored,
@@ -88,7 +88,7 @@ export async function loginWithQr(config, signal) {
     const apiBaseUrl = config.baseUrl ?? DEFAULT_API_BASE_URL;
     const qr = await fetchQRCode(apiBaseUrl, DEFAULT_ILINK_BOT_TYPE);
     const qrcodeUrl = qr.qrcode_img_content || qr.qrcode;
-    logger.info(`weixin-ilink QR login for ${config.name}: scan with WeChat ClawBot entry — ${qrcodeUrl.slice(0, 120)}${qrcodeUrl.length > 120 ? '…' : ''}`);
+    logger.info(`weixin-ilink QR login for ${config.id}: scan with WeChat ClawBot entry — ${qrcodeUrl.slice(0, 120)}${qrcodeUrl.length > 120 ? '…' : ''}`);
     const deadline = Date.now() + LOGIN_TIMEOUT_MS;
     let currentBaseUrl = apiBaseUrl;
     while (Date.now() < deadline) {
@@ -106,7 +106,7 @@ export async function loginWithQr(config, signal) {
                 throw new Error('扫码成功但未返回 bot_token');
             }
             const creds = {
-                botToken: status.bot_token ?? loadCredentials(config.name)?.botToken ?? '',
+                botToken: status.bot_token ?? loadCredentials(config.id)?.botToken ?? '',
                 ilinkUserId: status.ilink_user_id,
                 ilinkBotId: status.ilink_endpoint_id,
                 baseUrl: status.baseurl ?? currentBaseUrl,
@@ -114,7 +114,7 @@ export async function loginWithQr(config, signal) {
             if (!creds.botToken) {
                 throw new Error('binded_redirect 但本地无有效 bot_token');
             }
-            saveCredentials(config.name, creds);
+            saveCredentials(config.id, creds);
             return creds;
         }
         if (status.status === 'expired') {

package/lib/protocol.d.ts

@@ -2,10 +2,11 @@
  * Weixin iLink protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
+import type { ConversationRef } from '@zhin.js/im-contract';
 import type { WeixinMessage } from './ilink-types.js';
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface WeixinIlinkAdapterConfig {
-    readonly name?: string;
+    readonly id?: string;
     readonly botAgent?: string;
     readonly baseUrl?: string;
     readonly cdnBaseUrl?: string;
@@ -18,7 +19,7 @@ export interface WeixinIlinkAdapterConfig {
 }
 export interface ResolvedWeixinIlinkConfig {
     readonly context: 'weixin-ilink';
-    readonly name: string;
+    readonly id: string;
     readonly botAgent?: string;
     readonly baseUrl: string;
     readonly cdnBaseUrl: string;
@@ -43,6 +44,11 @@ export declare function resolveWeixinIlinkConfig(config?: WeixinIlinkAdapterConf
 /** Build inbound text for MessageGateway.receive (gateway owns reply routing). */
 export declare function formatInboundContent(msg: WeixinMessageWithMedia): string;
 export declare function inboundMessageId(msg: WeixinMessage): string;
+/**
+ * 入站归一化 → ConversationRef：个人微信无群/频道概念，全部会话都是
+ * 与 `from_user_id` 的 private 会话（无 parent）。
+ */
+export declare function weixinIlinkInboundConversation(endpointKey: string, userId: string): ConversationRef;
 /**
  * Wire-encode an already-rendered outbound payload into Weixin wire segments.
  * Segment canonicalization is intentionally not done here.

package/lib/protocol.js

@@ -9,8 +9,8 @@ import { DEFAULT_API_BASE_URL, DEFAULT_CDN_BASE_URL } from './ilink-meta.js';
 const DEFAULT_LONG_POLL_TIMEOUT_MS = 35_000;
 export function resolveWeixinIlinkConfig(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'weixin-ilink');
-    const name = (typeof config.name === 'string' && config.name)
-        || (typeof entry?.name === 'string' && entry.name)
+    const id = (typeof config.id === 'string' && config.id)
+        || (typeof entry?.id === 'string' && entry.id)
         || process.env.WEIXIN_ILINK_BOT_NAME
         || 'weixin-ilink-bot';
     const botToken = pickCredential(typeof config.botToken === 'string' ? config.botToken.trim() : config.botToken, typeof entry?.botToken === 'string' ? entry.botToken.trim() : entry?.botToken, process.env.WEIXIN_ILINK_TOKEN?.trim());
@@ -18,7 +18,7 @@ export function resolveWeixinIlinkConfig(config = {}) {
     // (sidecar credentials file / QR login) during endpoint.start().
     return {
         context: 'weixin-ilink',
-        name,
+        id,
         botAgent: config.botAgent ?? entry?.botAgent,
         baseUrl: config.baseUrl ?? entry?.baseUrl ?? DEFAULT_API_BASE_URL,
         cdnBaseUrl: config.cdnBaseUrl ?? entry?.cdnBaseUrl ?? DEFAULT_CDN_BASE_URL,
@@ -55,6 +55,17 @@ export function formatInboundContent(msg) {
 export function inboundMessageId(msg) {
     return String(msg.message_id ?? msg.client_id ?? msg.seq ?? Date.now());
 }
+/**
+ * 入站归一化 → ConversationRef：个人微信无群/频道概念，全部会话都是
+ * 与 `from_user_id` 的 private 会话（无 parent）。
+ */
+export function weixinIlinkInboundConversation(endpointKey, userId) {
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind: 'private',
+        id: userId,
+    };
+}
 /**
  * Wire-encode an already-rendered outbound payload into Weixin wire segments.
  * Segment canonicalization is intentionally not done here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-weixin-ilink",
-  "version": "5.0.1",
+  "version": "5.0.4",
   "type": "module",
   "description": "Zhin.js Weixin iLink (ClawBot) adapter for Plugin Runtime (long-poll)",
   "main": "./lib/index.js",
@@ -48,17 +48,18 @@
     }
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/command": "1.0.6",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/command": "1.0.9",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/logger": "1.0.76",
+    "@zhin.js/plugin-runtime": "1.1.5"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/plugin-runtime": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/plugin-runtime": "1.1.5",
+    "zhin.js": "6.0.4"
   },
   "peerDependenciesMeta": {
     "zhin.js": {

package/schema.json

@@ -18,24 +18,60 @@
       "type": "number",
       "default": 35000
     },
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（Weixin user id；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted Weixin user id"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
     "endpoints": {
       "type": "array",
-      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
       "items": {
         "type": "object",
         "additionalProperties": true,
         "properties": {
-          "name": {
-            "type": "string",
-            "description": "Weixin iLink bot name"
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（Weixin user id）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted Weixin user id"
+            },
+            "description": "本 endpoint 的 trusted 列表"
           },
           "botToken": {
             "type": "string",
             "description": "iLink bot token (prefer env WEIXIN_ILINK_TOKEN or sidecar credential file)"
+          },
+          "id": {
+            "type": "string",
+            "description": "Weixin iLink bot name"
           }
         },
         "required": [
-          "name",
+          "id",
           "botToken"
         ]
       }

package/src/credentials.ts

@@ -17,12 +17,12 @@ export function resolveStateDir(): string {
     : DEFAULT_DATA_DIR;
 }
 
-export function credentialsPath(endpointName: string): string {
-  return path.join(resolveStateDir(), `${endpointName}.json`);
+export function credentialsPath(endpointId: string): string {
+  return path.join(resolveStateDir(), `${endpointId}.json`);
 }
 
-export function loadCredentials(endpointName: string): WeixinIlinkCredentials | null {
-  const file = credentialsPath(endpointName);
+export function loadCredentials(endpointId: string): WeixinIlinkCredentials | null {
+  const file = credentialsPath(endpointId);
   try {
     if (!fs.existsSync(file)) return null;
     const raw = fs.readFileSync(file, "utf-8");
@@ -34,8 +34,8 @@ export function loadCredentials(endpointName: string): WeixinIlinkCredentials |
   }
 }
 
-export function saveCredentials(endpointName: string, creds: WeixinIlinkCredentials): void {
-  const file = credentialsPath(endpointName);
+export function saveCredentials(endpointId: string, creds: WeixinIlinkCredentials): void {
+  const file = credentialsPath(endpointId);
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(
     file,
@@ -44,12 +44,12 @@ export function saveCredentials(endpointName: string, creds: WeixinIlinkCredenti
   );
 }
 
-export function syncBufPath(endpointName: string): string {
-  return path.join(resolveStateDir(), `${endpointName}.sync-buf`);
+export function syncBufPath(endpointId: string): string {
+  return path.join(resolveStateDir(), `${endpointId}.sync-buf`);
 }
 
-export function loadSyncBuf(endpointName: string): string {
-  const file = syncBufPath(endpointName);
+export function loadSyncBuf(endpointId: string): string {
+  const file = syncBufPath(endpointId);
   try {
     return fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : "";
   } catch {
@@ -57,8 +57,8 @@ export function loadSyncBuf(endpointName: string): string {
   }
 }
 
-export function saveSyncBuf(endpointName: string, buf: string): void {
-  const file = syncBufPath(endpointName);
+export function saveSyncBuf(endpointId: string, buf: string): void {
+  const file = syncBufPath(endpointId);
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, buf, "utf-8");
 }

package/src/endpoint.ts

@@ -4,9 +4,14 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import type { EndpointFriend, EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type {
+  EndpointFriend,
+  EndpointInstance,
+  EndpointManagement,
+  EndpointSendRequest,
+} from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
-import { formatCompact, getLogger } from '@zhin.js/logger';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { getUpdates, notifyStart, notifyStop, sendTyping } from './ilink-api.js';
 import { configureIlinkMeta } from './ilink-meta.js';
@@ -44,13 +49,12 @@ import {
   inboundMessageId,
   segmentLocalPath,
   sleep,
+  weixinIlinkInboundConversation,
   type ResolvedWeixinIlinkConfig,
   type WeixinMessageWithMedia,
   type WeixinWireSegment,
 } from './protocol.js';
 
-const logger = getLogger('weixin-ilink');
-
 const MAX_CONSECUTIVE_FAILURES = 3;
 const BACKOFF_DELAY_MS = 30_000;
 const RETRY_DELAY_MS = 2_000;
@@ -80,6 +84,8 @@ export interface WeixinIlinkEndpointOptions {
 }
 
 export class WeixinIlinkEndpoint implements EndpointInstance {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
   readonly #options: WeixinIlinkEndpointOptions;
   readonly #resolveCredentials: (
     config: ResolvedWeixinIlinkConfig,
@@ -100,6 +106,7 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
   readonly management: EndpointManagement = createWeixinIlinkEndpointManagement(this);
 
   constructor(options: WeixinIlinkEndpointOptions) {
+    this.#logger = getAdapterLogger('weixin-ilink', options.config.id);
     this.#options = options;
     this.#resolveCredentials = options.resolveCredentials ?? resolveCredentials;
     this.#notifyStart = options.notifyStart ?? notifyStart;
@@ -114,7 +121,7 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
 
   /** Live endpoint 名（context token 按 account 名分桶，management 推导对端用）。 */
   get configName(): string {
-    return this.#options.config.name;
+    return this.#options.config.id;
   }
 
   apiBaseUrl(): string {
@@ -133,7 +140,7 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
       // QR 登录最长 8 分钟：stop() 必须能打断
       this.#loginAbort = new AbortController();
       this.#creds = await this.#resolveCredentials(this.#options.config, this.#loginAbort.signal);
-      restoreContextTokens(this.#options.config.name);
+      restoreContextTokens(this.#options.config.id);
 
       await this.#notifyStart({
         baseUrl: this.apiBaseUrl(),
@@ -142,19 +149,19 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
 
       this.#configManager = new WeixinConfigManager(
         { baseUrl: this.apiBaseUrl(), token: this.#creds.botToken },
-        (msg) => logger.debug(msg),
+        (msg) => this.#logger.debug(msg),
       );
 
       this.#pollAbort = new AbortController();
       this.#pollPromise = this.#pollLoop(this.#pollAbort.signal);
       this.#startMediaSweep();
-      logger.info(formatCompact({
+      this.#logger.info(formatCompact({
         op: 'connect',
-        endpoint: this.#options.config.name,
+        endpoint: this.#options.config.id,
       }));
     } catch (error) {
       await this.stop();
-      logger.error('Failed to connect weixin-ilink bot:', error);
+      this.#logger.error('Failed to connect weixin-ilink bot:', error);
       throw error;
     }
   }
@@ -178,12 +185,12 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
     }
     this.#stopMediaSweep();
     // 防抖中的 context token 落盘，避免 stop 丢尾部写入
-    flushContextTokenPersist(this.#options.config.name);
+    flushContextTokenPersist(this.#options.config.id);
     if (this.#creds?.botToken) {
       try {
         await this.#notifyStop({ baseUrl: this.apiBaseUrl(), token: this.#creds.botToken });
       } catch (err) {
-        logger.warn(formatCompact({
+        this.#logger.warn(formatCompact({
           op: 'notify_stop',
           ok: false,
           error: err instanceof Error ? err.message : String(err),
@@ -191,19 +198,20 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
       }
     }
     this.#started = false;
-    logger.debug(formatCompact({
-      op: 'disconnect',
-      endpoint: this.#options.config.name,
+    this.#logger.debug(formatCompact({
+          op: 'disconnect',
     }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     if (!this.#creds?.botToken) {
       throw new Error('weixin-ilink bot not authenticated');
     }
-    const contextToken = getContextToken(this.#options.config.name, target);
+    // 个人微信仅 private 会话，对端 user_id 即 conversation.id
+    const target = conversation.id;
+    const contextToken = getContextToken(this.#options.config.id, target);
     if (!contextToken) {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'send',
         ok: false,
         reason: 'missing_context_token',
@@ -261,7 +269,7 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
       }
 
       if (seg.type === 'image' || seg.type === 'video' || seg.type === 'file' || seg.type === 'record') {
-        logger.warn(formatCompact({
+        this.#logger.warn(formatCompact({
           op: 'send',
           skip: 'no_local_file',
           type: seg.type,
@@ -286,21 +294,21 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
     if (!this.#open) return;
     const userId = msg.from_user_id ?? '';
     if (msg.context_token && userId) {
-      setContextToken(this.#options.config.name, userId, msg.context_token);
+      setContextToken(this.#options.config.id, userId, msg.context_token);
     }
+    const conversation = weixinIlinkInboundConversation(String(this.#options.id), userId);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: userId,
+      conversation,
+      message: { conversation, id: inboundMessageId(msg) },
       content: formatInboundContent(msg),
-      sender: userId,
-      id: inboundMessageId(msg),
+      sender: { id: userId },
+      endpointId: this.#options.config.id,
       metadata: Object.freeze({
-        endpoint: this.#options.config.name,
         messageType: msg.message_type,
         createTimeMs: msg.create_time_ms,
       }),
     }).catch((err) => {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'weixin_ilink_gateway_receive_failed',
         target: userId,
         error: err instanceof Error ? err.message : String(err),
@@ -310,10 +318,10 @@ 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.name, userId);
+    const contextToken = getContextToken(this.#options.config.id, userId);
     const cfg = await this.#configManager.getForUser(userId, contextToken);
     if (!cfg.typingTicket) {
-      logger.debug(formatCompact({
+      this.#logger.debug(formatCompact({
         op: 'send_typing',
         skip: 'no_typing_ticket',
         userId,
@@ -334,14 +342,14 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
   async #pollLoop(abortSignal: AbortSignal): Promise<void> {
     if (!this.#creds?.botToken) return;
 
-    const endpointName = this.#options.config.name;
-    let getUpdatesBuf = loadSyncBuf(endpointName);
+    const endpointId = this.#options.config.id;
+    let getUpdatesBuf = loadSyncBuf(endpointId);
     let nextTimeoutMs = this.#options.config.longPollTimeoutMs;
     let consecutiveFailures = 0;
 
     while (!abortSignal.aborted) {
-      if (isSessionPaused(endpointName)) {
-        await sleep(getRemainingPauseMs(endpointName), abortSignal);
+      if (isSessionPaused(endpointId)) {
+        await sleep(getRemainingPauseMs(endpointId), abortSignal);
         continue;
       }
 
@@ -366,9 +374,9 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
           const sessionExpired =
             resp.errcode === SESSION_EXPIRED_ERRCODE || resp.ret === SESSION_EXPIRED_ERRCODE;
           if (sessionExpired) {
-            pauseSession(endpointName);
+            pauseSession(endpointId);
             consecutiveFailures = 0;
-            await sleep(getRemainingPauseMs(endpointName), abortSignal);
+            await sleep(getRemainingPauseMs(endpointId), abortSignal);
             continue;
           }
           consecutiveFailures += 1;
@@ -389,12 +397,12 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
         }
         if (nextBuf) {
           getUpdatesBuf = nextBuf;
-          saveSyncBuf(endpointName, getUpdatesBuf);
+          saveSyncBuf(endpointId, getUpdatesBuf);
         }
       } catch (err) {
         if (abortSignal.aborted) return;
         consecutiveFailures += 1;
-        logger.error(formatCompact({
+        this.#logger.error(formatCompact({
           op: 'poll',
           ok: false,
           error: err instanceof Error ? err.message : String(err),
@@ -411,14 +419,14 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
   async #handleInboundMessage(full: WeixinMessage): Promise<void> {
     const fromUserId = full.from_user_id ?? '';
     if (full.context_token && fromUserId) {
-      setContextToken(this.#options.config.name, fromUserId, full.context_token);
+      setContextToken(this.#options.config.id, fromUserId, full.context_token);
     }
 
     const mediaOpts = await this.#downloadInboundMedia(full);
     this.admit({ ...full, _media: mediaOpts });
-    logger.debug(formatCompact({
+    this.#logger.debug(formatCompact({
       op: 'recv',
-      endpoint: this.#options.config.name,
+      endpoint: this.#options.config.id,
       target: fromUserId,
       preview: formatInboundContent({ ...full, _media: mediaOpts }).slice(0, 80),
     }));
@@ -448,8 +456,8 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
       cdnBaseUrl: this.cdnBaseUrl(),
       saveMedia: (buffer, contentType, subdir, maxBytes, originalFilename) =>
         this.#saveInboundMedia(buffer, contentType, subdir, maxBytes, originalFilename),
-      log: (msg) => logger.debug(msg),
-      errLog: (msg) => logger.warn(msg),
+      log: (msg) => this.#logger.debug(msg),
+      errLog: (msg) => this.#logger.warn(msg),
       label: `inbound:${full.from_user_id ?? 'unknown'}`,
     });
   }
@@ -513,9 +521,9 @@ export class WeixinIlinkEndpoint implements EndpointInstance {
         const stat = fs.statSync(filePath);
         if (now - stat.mtimeMs <= INBOUND_MEDIA_TTL_MS) continue;
         fs.unlinkSync(filePath);
-        logger.debug(formatCompact({
+        this.#logger.debug(formatCompact({
           op: 'media_sweep',
-          endpoint: this.#options.config.name,
+          endpoint: this.#options.config.id,
           file: entry.name,
         }));
       } catch {

package/src/login.ts

@@ -106,7 +106,7 @@ export async function resolveCredentials(
 ): Promise<WeixinIlinkCredentials> {
   const envToken = process.env.WEIXIN_ILINK_TOKEN?.trim() || config.botToken?.trim();
   if (envToken) {
-    const stored = loadCredentials(config.name);
+    const stored = loadCredentials(config.id);
     return {
       botToken: envToken,
       ilinkUserId: stored?.ilinkUserId,
@@ -115,7 +115,7 @@ export async function resolveCredentials(
     };
   }
 
-  const stored = loadCredentials(config.name);
+  const stored = loadCredentials(config.id);
   if (stored?.botToken) {
     return {
       ...stored,
@@ -135,7 +135,7 @@ export async function loginWithQr(
   const qrcodeUrl = qr.qrcode_img_content || qr.qrcode;
 
   logger.info(
-    `weixin-ilink QR login for ${config.name}: scan with WeChat ClawBot entry — ${qrcodeUrl.slice(0, 120)}${qrcodeUrl.length > 120 ? '…' : ''}`,
+    `weixin-ilink QR login for ${config.id}: scan with WeChat ClawBot entry — ${qrcodeUrl.slice(0, 120)}${qrcodeUrl.length > 120 ? '…' : ''}`,
   );
 
   const deadline = Date.now() + LOGIN_TIMEOUT_MS;
@@ -157,7 +157,7 @@ export async function loginWithQr(
         throw new Error('扫码成功但未返回 bot_token');
       }
       const creds: WeixinIlinkCredentials = {
-        botToken: status.bot_token ?? loadCredentials(config.name)?.botToken ?? '',
+        botToken: status.bot_token ?? loadCredentials(config.id)?.botToken ?? '',
         ilinkUserId: status.ilink_user_id,
         ilinkBotId: status.ilink_endpoint_id,
         baseUrl: status.baseurl ?? currentBaseUrl,
@@ -165,7 +165,7 @@ export async function loginWithQr(
       if (!creds.botToken) {
         throw new Error('binded_redirect 但本地无有效 bot_token');
       }
-      saveCredentials(config.name, creds);
+      saveCredentials(config.id, creds);
       return creds;
     }
 

package/src/protocol.ts

@@ -5,13 +5,14 @@
 
 import { pickCredential } from '@zhin.js/adapter';
 import { isMediaRef } from '@zhin.js/core';
+import type { ConversationRef } from '@zhin.js/im-contract';
 import { bodyFromItemList, isMediaItem } from './weixin-inbound.js';
 import { DEFAULT_API_BASE_URL, DEFAULT_CDN_BASE_URL } from './ilink-meta.js';
 import type { WeixinMessage } from './ilink-types.js';
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface WeixinIlinkAdapterConfig {
-  readonly name?: string;
+  readonly id?: string;
   readonly botAgent?: string;
   readonly baseUrl?: string;
   readonly cdnBaseUrl?: string;
@@ -25,7 +26,7 @@ export interface WeixinIlinkAdapterConfig {
 
 export interface ResolvedWeixinIlinkConfig {
   readonly context: 'weixin-ilink';
-  readonly name: string;
+  readonly id: string;
   readonly botAgent?: string;
   readonly baseUrl: string;
   readonly cdnBaseUrl: string;
@@ -57,8 +58,8 @@ export function resolveWeixinIlinkConfig(
   config: WeixinIlinkAdapterConfig = {},
 ): ResolvedWeixinIlinkConfig {
   const entry = config.endpoints?.find((item) => item.context === 'weixin-ilink');
-  const name = (typeof config.name === 'string' && config.name)
-    || (typeof entry?.name === 'string' && entry.name)
+  const id = (typeof config.id === 'string' && config.id)
+    || (typeof entry?.id === 'string' && entry.id)
     || process.env.WEIXIN_ILINK_BOT_NAME
     || 'weixin-ilink-bot';
   const botToken = pickCredential(
@@ -70,7 +71,7 @@ export function resolveWeixinIlinkConfig(
   // (sidecar credentials file / QR login) during endpoint.start().
   return {
     context: 'weixin-ilink',
-    name,
+    id,
     botAgent: config.botAgent ?? entry?.botAgent,
     baseUrl: config.baseUrl ?? entry?.baseUrl ?? DEFAULT_API_BASE_URL,
     cdnBaseUrl: config.cdnBaseUrl ?? entry?.cdnBaseUrl ?? DEFAULT_CDN_BASE_URL,
@@ -107,6 +108,18 @@ export function inboundMessageId(msg: WeixinMessage): string {
   return String(msg.message_id ?? msg.client_id ?? msg.seq ?? Date.now());
 }
 
+/**
+ * 入站归一化 → ConversationRef：个人微信无群/频道概念，全部会话都是
+ * 与 `from_user_id` 的 private 会话（无 parent）。
+ */
+export function weixinIlinkInboundConversation(endpointKey: string, userId: string): ConversationRef {
+  return {
+    endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+    kind: 'private',
+    id: userId,
+  };
+}
+
 /**
  * Wire-encode an already-rendered outbound payload into Weixin wire segments.
  * Segment canonicalization is intentionally not done here.

package/src/silk-wasm.d.ts

@@ -1,6 +1,10 @@
-declare module "silk-wasm" {
+/**
+ * silk-wasm 是纯可选运行时依赖（不入 package.json）：silk-transcode.ts 在
+ * try/catch 里动态 import，缺失时降级返回 null。这里只声明用到的最小表面。
+ */
+declare module 'silk-wasm' {
   export function decode(
-    buf: Buffer,
+    input: Uint8Array,
     sampleRate: number,
   ): Promise<{ data: Uint8Array; duration: number }>;
 }