evolcore 0.0.3 → 0.0.5

package/dist/channels/wechat.js

@@ -7,11 +7,31 @@ import { sanitizeFileName, saveToUploads, safeFetch, bufferToInboundImage } from
 import { markdownToPlainText } from '../utils/markdown-to-plain-text.js';
 import { DEFAULT_FLUSH_DELAY_SECONDS } from '../types.js';
 import { formatItemsAsText } from '../core/message/items-formatter.js';
+import { createSendFileMarkerPattern } from '../core/message/file-markers.js';
 import { initWelcomeManager, sendWelcomeIfNeeded } from '../utils/welcome.js';
-const CHANNEL_VERSION = '1.0.0';
+import { ContactBindCodeRegistry, handleExplicitContactBindCommand, } from '../config/contact-bind-code.js';
+const wechatContactBinds = new ContactBindCodeRegistry({
+    channelType: 'wechat',
+    displayName: '微信',
+    initCommand: 'ec init wechat',
+});
+export function registerPendingWechatContactBind(req) {
+    return wechatContactBinds.register(req);
+}
+export function handlePendingWechatContactBindMessage(ctx) {
+    return handleExplicitContactBindCommand(wechatContactBinds, ctx);
+}
+export function getPendingWechatContactBind(selfAid, channelName, primaryId) {
+    return wechatContactBinds.get(selfAid, channelName, primaryId);
+}
+export function clearPendingWechatContactBinds() {
+    wechatContactBinds.clear();
+}
+const CHANNEL_VERSION = '2.4.6';
 const ILINK_APP_ID = 'bot';
 // iLink-App-ClientVersion: major<<16 | minor<<8 | patch (uint32)
-const ILINK_APP_CLIENT_VERSION = String((1 << 16) | (0 << 8) | 0); // 1.0.0 = 65536
+const ILINK_APP_CLIENT_VERSION = String((2 << 16) | (4 << 8) | 6); // 2.4.6 = 132102
+const BOT_AGENT = 'EvolCore';
 const DEFAULT_LONG_POLL_TIMEOUT_MS = 35_000;
 const DEFAULT_API_TIMEOUT_MS = 15_000;
 const DEFAULT_CONFIG_TIMEOUT_MS = 10_000;
@@ -20,8 +40,65 @@ const BACKOFF_DELAY_MS = 30_000;
 const RETRY_DELAY_MS = 2_000;
 const TYPING_TICKET_TTL_MS = 5 * 60 * 1000; // 5 min cache
 const SESSION_EXPIRED_ERRCODE = -14;
-const SESSION_RETRY_DELAY_MS = 30_000; // 短暂停：30s 后重试一次
-const SESSION_PAUSE_DURATION_MS = 10 * 60 * 1000; // 长暂停：10 分钟
+export class WechatApiError extends Error {
+    endpoint;
+    ret;
+    errcode;
+    errmsg;
+    code;
+    constructor(endpoint, ret, errcode, errmsg) {
+        const code = errcode !== undefined && errcode !== 0 ? errcode : ret;
+        super(`${endpoint} failed: ret=${ret ?? 'unset'} errcode=${errcode ?? 'unset'} errmsg=${errmsg ?? '(none)'}`);
+        this.endpoint = endpoint;
+        this.ret = ret;
+        this.errcode = errcode;
+        this.errmsg = errmsg;
+        this.name = 'WechatApiError';
+        this.code = code;
+    }
+    hasCode(code) {
+        return this.ret === code || this.errcode === code;
+    }
+}
+export class WechatContextTokenRefreshRequiredError extends Error {
+    recipient;
+    constructor(recipient, options) {
+        super(`sendmessage ret=-2 for ${recipient}; waiting for an updated context_token`);
+        this.recipient = recipient;
+        this.name = 'WechatContextTokenRefreshRequiredError';
+        if (options?.cause !== undefined) {
+            this.cause = options.cause;
+        }
+    }
+}
+/** Classify fetch/undici failures using the categories exposed by Tencent 2.4.6. */
+export function classifyFetchError(err) {
+    if (err instanceof Error && err.name === 'AbortError') {
+        return { type: 'timeout', description: 'request timeout' };
+    }
+    const root = err;
+    const cause = root?.cause;
+    const causeCode = typeof cause === 'object' && cause ? cause.code ?? '' : '';
+    const rootCode = root?.code ?? '';
+    const matchedCode = causeCode || rootCode || (typeof cause === 'string' ? cause : '');
+    const searchable = `${String(cause ?? err ?? '')} ${causeCode} ${rootCode}`;
+    if (/ENOTFOUND|EAI_AGAIN|getaddrinfo/i.test(searchable)) {
+        return { type: 'dns', description: 'DNS resolution failed, check DNS configuration', ...(matchedCode ? { code: matchedCode } : {}) };
+    }
+    if (/ECONNREFUSED/i.test(searchable)) {
+        return { type: 'tcp', description: 'TCP connection refused', ...(matchedCode ? { code: matchedCode } : {}) };
+    }
+    if (/UND_ERR_CONNECT_TIMEOUT|ETIMEDOUT|ENETUNREACH|EHOSTUNREACH/i.test(searchable)) {
+        return { type: 'tcp', description: 'TCP connection timeout or unreachable', ...(matchedCode ? { code: matchedCode } : {}) };
+    }
+    if (/UND_ERR_SOCKET|SSL|TLS|CERT|UNABLE_TO_VERIFY|DEPTH_ZERO/i.test(searchable)) {
+        return { type: 'tls', description: 'TLS handshake error', ...(matchedCode ? { code: matchedCode } : {}) };
+    }
+    return { type: 'unknown', description: 'network request failed', ...(matchedCode ? { code: matchedCode } : {}) };
+}
+function buildBaseInfo() {
+    return { channel_version: CHANNEL_VERSION, bot_agent: BOT_AGENT };
+}
 const MSG_TYPE_USER = 1;
 const MSG_TYPE_BOT = 2;
 const MSG_ITEM_TEXT = 1;
@@ -109,14 +186,18 @@ export class WechatChannel {
     recallHandler;
     abortController;
     connected = false;
+    connectionState = 'disconnected';
+    lastError;
+    reauthRequiredAt;
+    inflightHandlers = new Set();
     // 内部状态（不外泄到核心层）
     contextTokenCache = new Map();
+    rejectedContextTokens = new Map();
+    pendingContextMessages = new Map();
     typingTicketCache = new Map();
     getUpdatesBuf = '';
     syncBufPath;
     contextTokensPath;
-    // Session expired 状态
-    sessionPausedUntil = 0;
     onSessionExpired;
     eventBus;
     // Project path resolver（用于保存文件到 uploads 目录）
@@ -150,14 +231,17 @@ export class WechatChannel {
     setEventBus(bus) {
         this.eventBus = bus;
     }
-    /** 当前是否处于 session 暂停状态 */
+    /** 当前 token 是否已失效，保留旧方法名以兼容现有调用方。 */
     isSessionPaused() {
-        return Date.now() < this.sessionPausedUntil;
+        return this.connectionState === 'reauth_required';
     }
     async connect() {
         if (!this.config.token) {
             throw new Error('WeChat token not configured');
         }
+        if (this.connectionState === 'reauth_required') {
+            throw new Error('WeChat reauthentication required; run: ec init wechat');
+        }
         // 恢复游标
         try {
             if (fs.existsSync(this.syncBufPath)) {
@@ -173,6 +257,8 @@ export class WechatChannel {
             await this.notifyLifecycle('notifystart');
         }
         catch (err) {
+            if (this.isSessionPaused())
+                throw err;
             logger.warn('[WeChat] notifyStart failed during startup (ignored):', err);
         }
         this.abortController = new AbortController();
@@ -182,8 +268,14 @@ export class WechatChannel {
                 return;
             logger.error('[WeChat] Poll loop fatal error:', err);
             this.connected = false;
+            if (this.connectionState !== 'reauth_required') {
+                this.connectionState = 'disconnected';
+                this.lastError = err instanceof Error ? err.message : String(err);
+            }
         });
         this.connected = true;
+        this.connectionState = 'connected';
+        this.lastError = undefined;
         logger.info('[WeChat] Channel connected');
     }
     async disconnect() {
@@ -192,21 +284,35 @@ export class WechatChannel {
             this.abortController.abort();
             this.abortController = undefined;
         }
+        const reauthRequired = this.connectionState === 'reauth_required';
+        if (!reauthRequired)
+            this.connectionState = 'disconnected';
         // 通知 ilink 后端：bot 下线
-        try {
-            await this.notifyLifecycle('notifystop');
-        }
-        catch (err) {
-            logger.warn('[WeChat] notifyStop failed during shutdown (ignored):', err);
+        if (!reauthRequired) {
+            try {
+                await this.notifyLifecycle('notifystop');
+            }
+            catch (err) {
+                logger.warn('[WeChat] notifyStop failed during shutdown (ignored):', err);
+            }
         }
         logger.info('[WeChat] Channel disconnected');
     }
     /** Get current connection status */
     getStatus() {
-        return { connected: this.connected };
+        return {
+            connected: this.connected,
+            state: this.connectionState,
+            pendingContextMessages: this.pendingContextMessages.size,
+            ...(this.lastError ? { error: this.lastError } : {}),
+            ...(this.reauthRequiredAt ? { reauthRequiredAt: this.reauthRequiredAt } : {}),
+        };
     }
     /** Reconnect: disconnect then connect again */
     async reconnect() {
+        if (this.connectionState === 'reauth_required') {
+            return '重连失败: 微信 token 已失效，请运行 ec init wechat 重新认证';
+        }
         await this.disconnect();
         try {
             await this.connect();
@@ -221,12 +327,7 @@ export class WechatChannel {
             logger.warn('[WeChat] Attempted to send empty message, skipping');
             return;
         }
-        // Session 暂停期间拒绝发送
-        if (this.isSessionPaused()) {
-            const remainingMin = Math.ceil((this.sessionPausedUntil - Date.now()) / 60_000);
-            logger.warn(`[WeChat] Session paused, ${remainingMin}min remaining, dropping outbound to ${to}`);
-            return;
-        }
+        this.assertAuthenticated();
         const contextToken = this.contextTokenCache.get(to);
         if (!contextToken) {
             logger.error(`[WeChat] No context_token for ${to}, cannot send message`);
@@ -235,21 +336,11 @@ export class WechatChannel {
         // Markdown → 纯文本
         const plainText = markdownToPlainText(text);
         const clientId = `evolcore-wechat:${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
-        const body = {
-            msg: {
-                from_user_id: '',
-                to_user_id: to,
-                client_id: clientId,
-                message_type: MSG_TYPE_BOT,
-                message_state: MSG_STATE_FINISH,
-                item_list: [{ type: MSG_ITEM_TEXT, text_item: { text: plainText } }],
-                context_token: contextToken,
-            },
-            base_info: { channel_version: CHANNEL_VERSION },
-        };
         try {
-            await this.apiFetch('ilink/bot/sendmessage', JSON.stringify(body), DEFAULT_API_TIMEOUT_MS);
-            logger.debug(`[WeChat] Sent message to ${to}, clientId=${clientId}`);
+            const delivery = await this.sendMessageItemWithContextRetry(to, { type: MSG_ITEM_TEXT, text_item: { text: plainText } }, contextToken, clientId);
+            if (delivery === 'sent') {
+                logger.debug(`[WeChat] Sent message to ${to}, clientId=${clientId}`);
+            }
         }
         catch (err) {
             logger.error(`[WeChat] Failed to send message to ${to}:`, err);
@@ -262,11 +353,7 @@ export class WechatChannel {
     }
     /** 发送文件（图片/视频/文件）给用户，通过 CDN 上传 */
     async sendFile(to, filePath) {
-        // Session 暂停期间拒绝发送
-        if (this.isSessionPaused()) {
-            logger.warn(`[WeChat] Session paused, dropping file send to ${to}`);
-            return;
-        }
+        this.assertAuthenticated();
         const contextToken = this.contextTokenCache.get(to);
         if (!contextToken) {
             logger.error(`[WeChat] No context_token for ${to}, cannot send file`);
@@ -319,15 +406,15 @@ export class WechatChannel {
         let consecutiveFailures = 0;
         let nextTimeoutMs = DEFAULT_LONG_POLL_TIMEOUT_MS;
         logger.info('[WeChat] Starting message polling...');
-        while (!signal.aborted) {
+        while (!signal.aborted && this.connectionState !== 'reauth_required') {
             try {
                 const body = JSON.stringify({
                     get_updates_buf: this.getUpdatesBuf,
-                    base_info: { channel_version: CHANNEL_VERSION },
+                    base_info: buildBaseInfo(),
                 });
-                let rawText;
+                let resp;
                 try {
-                    rawText = await this.apiFetch('ilink/bot/getupdates', body, nextTimeoutMs, signal);
+                    resp = await this.apiRequest('ilink/bot/getupdates', body, nextTimeoutMs, signal);
                 }
                 catch (err) {
                     if (signal.aborted)
@@ -338,93 +425,10 @@ export class WechatChannel {
                     }
                     throw err;
                 }
-                const resp = JSON.parse(rawText);
                 // 更新服务端建议的轮询超时
                 if (resp.longpolling_timeout_ms != null && resp.longpolling_timeout_ms > 0) {
                     nextTimeoutMs = resp.longpolling_timeout_ms;
                 }
-                // API 错误处理
-                const isError = (resp.ret !== undefined && resp.ret !== 0) ||
-                    (resp.errcode !== undefined && resp.errcode !== 0);
-                if (isError) {
-                    // Session expired 专用处理
-                    const isSessionExpired = resp.errcode === SESSION_EXPIRED_ERRCODE || resp.ret === SESSION_EXPIRED_ERRCODE;
-                    if (isSessionExpired) {
-                        consecutiveFailures = 0;
-                        logger.error(`[WeChat] Session expired (errcode=${resp.errcode}), retrying in ${SESSION_RETRY_DELAY_MS / 1000}s...`);
-                        // 短暂停后重试一次
-                        await this.sleep(SESSION_RETRY_DELAY_MS, signal);
-                        if (signal.aborted)
-                            return;
-                        // 重试 getupdates
-                        try {
-                            const retryBody = JSON.stringify({
-                                get_updates_buf: this.getUpdatesBuf,
-                                base_info: { channel_version: CHANNEL_VERSION },
-                            });
-                            const retryRaw = await this.apiFetch('ilink/bot/getupdates', retryBody, nextTimeoutMs, signal);
-                            const retryResp = JSON.parse(retryRaw);
-                            const retryExpired = retryResp.errcode === SESSION_EXPIRED_ERRCODE || retryResp.ret === SESSION_EXPIRED_ERRCODE;
-                            if (!retryExpired) {
-                                // 恢复成功，静默继续
-                                logger.info('[WeChat] Session recovered after retry');
-                                // 把 retryResp 当正常响应处理（更新游标和消息）
-                                if (retryResp.get_updates_buf) {
-                                    this.getUpdatesBuf = retryResp.get_updates_buf;
-                                    try {
-                                        fs.writeFileSync(this.syncBufPath, this.getUpdatesBuf, 'utf-8');
-                                    }
-                                    catch { }
-                                }
-                                for (const msg of retryResp.msgs ?? []) {
-                                    await this.handleInboundMessage(msg);
-                                }
-                                continue;
-                            }
-                        }
-                        catch (retryErr) {
-                            if (signal.aborted)
-                                return;
-                            logger.error('[WeChat] Retry after session expired also failed:', retryErr);
-                        }
-                        // 重试仍失败，进入长暂停
-                        const pauseMin = SESSION_PAUSE_DURATION_MS / 60_000;
-                        this.sessionPausedUntil = Date.now() + SESSION_PAUSE_DURATION_MS;
-                        logger.error(`[WeChat] Session still expired, pausing for ${pauseMin}min`);
-                        // 通知用户（通过事件总线或回调）
-                        const authMsg = `⚠️ 微信 token 已过期，通道暂停 ${pauseMin} 分钟后自动重试。\n如需立即恢复，请运行: ec init wechat`;
-                        if (this.eventBus) {
-                            this.eventBus.publish({
-                                type: 'channel:error',
-                                channel: 'wechat',
-                                status: 'auth_error',
-                                message: authMsg,
-                                timestamp: Date.now(),
-                            });
-                        }
-                        else if (this.onSessionExpired) {
-                            this.onSessionExpired(authMsg);
-                        }
-                        await this.sleep(SESSION_PAUSE_DURATION_MS, signal);
-                        if (signal.aborted)
-                            return;
-                        // 长暂停结束，清除暂停状态，循环自动重试
-                        this.sessionPausedUntil = 0;
-                        logger.info('[WeChat] Session pause ended, resuming polling');
-                        continue;
-                    }
-                    consecutiveFailures++;
-                    logger.error(`[WeChat] getUpdates failed: ret=${resp.ret} errcode=${resp.errcode} errmsg=${resp.errmsg ?? ''}`);
-                    if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
-                        logger.error(`[WeChat] ${MAX_CONSECUTIVE_FAILURES} consecutive failures, backing off ${BACKOFF_DELAY_MS / 1000}s`);
-                        consecutiveFailures = 0;
-                        await this.sleep(BACKOFF_DELAY_MS, signal);
-                    }
-                    else {
-                        await this.sleep(RETRY_DELAY_MS, signal);
-                    }
-                    continue;
-                }
                 consecutiveFailures = 0;
                 // 保存游标
                 if (resp.get_updates_buf) {
@@ -444,8 +448,18 @@ export class WechatChannel {
             catch (err) {
                 if (signal.aborted)
                     return;
+                if (this.isSessionPaused())
+                    return;
                 consecutiveFailures++;
-                logger.error(`[WeChat] Poll error (${consecutiveFailures}/${MAX_CONSECUTIVE_FAILURES}):`, err);
+                if (err instanceof WechatApiError) {
+                    logger.error(`[WeChat] getUpdates API error (${consecutiveFailures}/${MAX_CONSECUTIVE_FAILURES}): ${err.message}`);
+                }
+                else {
+                    const classified = classifyFetchError(err);
+                    logger.error(`[WeChat] Poll network error (${consecutiveFailures}/${MAX_CONSECUTIVE_FAILURES}): ` +
+                        `type=${classified.type} description=${classified.description}` +
+                        `${classified.code ? ` code=${classified.code}` : ''}`, err);
+                }
                 if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
                     consecutiveFailures = 0;
                     await this.sleep(BACKOFF_DELAY_MS, signal);
@@ -463,8 +477,13 @@ export class WechatChannel {
         const fromUserId = msg.from_user_id ?? '';
         // 缓存 context_token
         if (msg.context_token) {
+            const previousContextToken = this.contextTokenCache.get(fromUserId);
             this.contextTokenCache.set(fromUserId, msg.context_token);
             this.persistContextTokens();
+            if (msg.context_token !== previousContextToken) {
+                this.rejectedContextTokens.delete(fromUserId);
+                this.retryPendingContextMessage(fromUserId, msg.context_token);
+            }
         }
         // 提取文本（原有逻辑）
         const text = extractTextFromMessage(msg);
@@ -483,12 +502,13 @@ export class WechatChannel {
         await sendWelcomeIfNeeded(this.welcomeManager, fromUserId, fromUserId, (id, text) => this.sendMessage(id, text), 'WeChat');
         // 回调主流程
         if (this.messageHandler) {
-            try {
-                await this.messageHandler(fromUserId, finalContent || '', fromUserId, media.images.length ? media.images : undefined, 'private');
-            }
-            catch (err) {
+            const task = Promise.resolve()
+                .then(() => this.messageHandler(fromUserId, finalContent || '', fromUserId, media.images.length ? media.images : undefined, 'private'))
+                .catch(err => {
                 logger.error('[WeChat] Message handler error:', err);
-            }
+            });
+            this.inflightHandlers.add(task);
+            void task.finally(() => this.inflightHandlers.delete(task));
         }
     }
     // ── Acknowledge (sendTyping) ──────────────────────────────────────────
@@ -501,9 +521,9 @@ export class WechatChannel {
                 ilink_user_id: fromUserId,
                 typing_ticket: ticket,
                 status: 1, // typing
-                base_info: { channel_version: CHANNEL_VERSION },
+                base_info: buildBaseInfo(),
             });
-            await this.apiFetch('ilink/bot/sendtyping', body, DEFAULT_CONFIG_TIMEOUT_MS);
+            await this.apiRequest('ilink/bot/sendtyping', body, DEFAULT_CONFIG_TIMEOUT_MS);
             logger.debug(`[WeChat] Sent typing indicator to ${fromUserId}`);
         }
         catch {
@@ -519,11 +539,10 @@ export class WechatChannel {
             const body = JSON.stringify({
                 ilink_user_id: userId,
                 context_token: contextToken,
-                base_info: { channel_version: CHANNEL_VERSION },
+                base_info: buildBaseInfo(),
             });
-            const rawText = await this.apiFetch('ilink/bot/getconfig', body, DEFAULT_CONFIG_TIMEOUT_MS);
-            const resp = JSON.parse(rawText);
-            if (resp.ret === 0 && resp.typing_ticket) {
+            const resp = await this.apiRequest('ilink/bot/getconfig', body, DEFAULT_CONFIG_TIMEOUT_MS);
+            if (resp.typing_ticket) {
                 this.typingTicketCache.set(userId, { ticket: resp.typing_ticket, fetchedAt: Date.now() });
                 return resp.typing_ticket;
             }
@@ -579,10 +598,9 @@ export class WechatChannel {
     async getUploadUrl(params) {
         const body = JSON.stringify({
             ...params,
-            base_info: { channel_version: CHANNEL_VERSION },
+            base_info: buildBaseInfo(),
         });
-        const raw = await this.apiFetch('ilink/bot/getuploadurl', body, DEFAULT_API_TIMEOUT_MS);
-        const resp = JSON.parse(raw);
+        const resp = await this.apiRequest('ilink/bot/getuploadurl', body, DEFAULT_API_TIMEOUT_MS);
         if (!resp.upload_param)
             throw new Error('getuploadurl: no upload_param');
         return resp;
@@ -633,7 +651,13 @@ export class WechatChannel {
     }
     async sendMediaMessage(to, item, contextToken) {
         const clientId = `evolcore-wechat:${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
-        const body = {
+        const delivery = await this.sendMessageItemWithContextRetry(to, item, contextToken, clientId);
+        if (delivery === 'sent') {
+            logger.info(`[WeChat] Sent media to ${to}, type=${item.type}`);
+        }
+    }
+    buildSendMessageBody(to, item, contextToken, clientId) {
+        return JSON.stringify({
             msg: {
                 from_user_id: '',
                 to_user_id: to,
@@ -643,27 +667,110 @@ export class WechatChannel {
                 item_list: [item],
                 context_token: contextToken,
             },
-            base_info: { channel_version: CHANNEL_VERSION },
-        };
-        await this.apiFetch('ilink/bot/sendmessage', JSON.stringify(body), DEFAULT_API_TIMEOUT_MS);
-        logger.info(`[WeChat] Sent media to ${to}, type=${item.type}`);
+            base_info: buildBaseInfo(),
+        });
+    }
+    async sendMessageItemWithContextRetry(to, item, initialContextToken, clientId) {
+        if (this.rejectedContextTokens.get(to) === initialContextToken) {
+            this.deferUntilContextTokenRefresh(to, item, clientId);
+            return 'deferred';
+        }
+        try {
+            await this.apiRequest('ilink/bot/sendmessage', this.buildSendMessageBody(to, item, initialContextToken, clientId), DEFAULT_API_TIMEOUT_MS);
+            return 'sent';
+        }
+        catch (err) {
+            if (!(err instanceof WechatApiError) ||
+                !err.hasCode(-2) ||
+                err.hasCode(SESSION_EXPIRED_ERRCODE)) {
+                throw err;
+            }
+            const updatedContextToken = this.contextTokenCache.get(to);
+            if (!updatedContextToken || updatedContextToken === initialContextToken) {
+                this.rejectedContextTokens.set(to, initialContextToken);
+                this.deferUntilContextTokenRefresh(to, item, clientId, err);
+                return 'deferred';
+            }
+            logger.warn(`[WeChat] sendmessage ret=-2 for ${to}; retrying once with updated context_token`);
+            try {
+                await this.apiRequest('ilink/bot/sendmessage', this.buildSendMessageBody(to, item, updatedContextToken, clientId), DEFAULT_API_TIMEOUT_MS);
+                return 'sent';
+            }
+            catch (retryError) {
+                if (retryError instanceof WechatApiError && retryError.hasCode(-2)) {
+                    this.rejectedContextTokens.set(to, updatedContextToken);
+                }
+                throw retryError;
+            }
+        }
+    }
+    deferUntilContextTokenRefresh(to, item, clientId, cause) {
+        const replaced = this.pendingContextMessages.has(to);
+        this.pendingContextMessages.set(to, { item, clientId });
+        const error = new WechatContextTokenRefreshRequiredError(to, { cause });
+        logger.warn(`[WeChat] ${error.message}; deferred latest outbound` +
+            `${replaced ? ' (replaced older deferred outbound)' : ''}`);
+    }
+    retryPendingContextMessage(to, updatedContextToken) {
+        const pending = this.pendingContextMessages.get(to);
+        if (!pending)
+            return;
+        this.pendingContextMessages.delete(to);
+        void this.apiRequest('ilink/bot/sendmessage', this.buildSendMessageBody(to, pending.item, updatedContextToken, pending.clientId), DEFAULT_API_TIMEOUT_MS).then(() => {
+            logger.info(`[WeChat] Delivered deferred outbound to ${to} after context_token refresh`);
+        }).catch(err => {
+            if (err instanceof WechatApiError && err.hasCode(-2)) {
+                this.rejectedContextTokens.set(to, updatedContextToken);
+            }
+            logger.error(`[WeChat] Deferred outbound retry failed for ${to}:`, err);
+        });
     }
     // ── ilink API Helpers ─────────────────────────────────────────────────
     /** Notify ilink backend of bot lifecycle events (start/stop). */
     async notifyLifecycle(action) {
-        const body = JSON.stringify({ base_info: { channel_version: CHANNEL_VERSION } });
-        await this.apiFetch(`ilink/bot/msg/${action}`, body, DEFAULT_CONFIG_TIMEOUT_MS);
+        const body = JSON.stringify({ base_info: buildBaseInfo() });
+        await this.apiRequest(`ilink/bot/msg/${action}`, body, DEFAULT_CONFIG_TIMEOUT_MS);
         logger.info(`[WeChat] ${action} succeeded`);
     }
+    async apiRequest(endpoint, body, timeoutMs, externalSignal) {
+        const rawText = await this.apiFetch(endpoint, body, timeoutMs, externalSignal);
+        let parsed;
+        try {
+            parsed = JSON.parse(rawText);
+        }
+        catch {
+            throw new Error(`${endpoint} returned invalid JSON`);
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error(`${endpoint} returned an invalid response`);
+        }
+        const resp = parsed;
+        const hasError = (resp.ret !== undefined && resp.ret !== 0) ||
+            (resp.errcode !== undefined && resp.errcode !== 0);
+        if (hasError) {
+            const apiError = new WechatApiError(endpoint, resp.ret, resp.errcode, resp.errmsg);
+            if (apiError.hasCode(SESSION_EXPIRED_ERRCODE)) {
+                this.enterReauthRequired(apiError);
+            }
+            throw apiError;
+        }
+        return resp;
+    }
     async apiFetch(endpoint, body, timeoutMs, externalSignal) {
+        this.assertAuthenticated();
         const base = this.config.baseUrl.endsWith('/') ? this.config.baseUrl : `${this.config.baseUrl}/`;
         const url = new URL(endpoint, base).toString();
-        const headers = this.buildHeaders(body);
+        const headers = this.buildHeaders();
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeoutMs);
         // 外部 signal（来自 disconnect）也要能中断
         const onExternalAbort = () => controller.abort();
-        externalSignal?.addEventListener('abort', onExternalAbort, { once: true });
+        if (externalSignal?.aborted) {
+            controller.abort();
+        }
+        else {
+            externalSignal?.addEventListener('abort', onExternalAbort, { once: true });
+        }
         try {
             const res = await fetch(url, {
                 method: 'POST',
@@ -671,27 +778,28 @@ export class WechatChannel {
                 body,
                 signal: controller.signal,
             });
-            clearTimeout(timer);
             const text = await res.text();
             if (!res.ok)
                 throw new Error(`HTTP ${res.status}: ${text}`);
             return text;
         }
         catch (err) {
-            clearTimeout(timer);
+            const classified = classifyFetchError(err);
+            logger.error(`[WeChat] API request failed: endpoint=${endpoint} type=${classified.type} ` +
+                `description=${classified.description}${classified.code ? ` code=${classified.code}` : ''}`);
             throw err;
         }
         finally {
+            clearTimeout(timer);
             externalSignal?.removeEventListener('abort', onExternalAbort);
         }
     }
-    buildHeaders(body) {
+    buildHeaders() {
         const uint32 = crypto.randomBytes(4).readUInt32BE(0);
         const wechatUin = Buffer.from(String(uint32), 'utf-8').toString('base64');
         const headers = {
             'Content-Type': 'application/json',
             'AuthorizationType': 'ilink_bot_token',
-            'Content-Length': String(Buffer.byteLength(body, 'utf-8')),
             'X-WECHAT-UIN': wechatUin,
             'iLink-App-Id': ILINK_APP_ID,
             'iLink-App-ClientVersion': ILINK_APP_CLIENT_VERSION,
@@ -701,6 +809,42 @@ export class WechatChannel {
         }
         return headers;
     }
+    assertAuthenticated() {
+        if (this.connectionState === 'reauth_required') {
+            throw new Error('WeChat reauthentication required; run: ec init wechat');
+        }
+    }
+    enterReauthRequired(error) {
+        if (this.connectionState === 'reauth_required')
+            return;
+        this.connected = false;
+        this.connectionState = 'reauth_required';
+        this.lastError = error.message;
+        this.reauthRequiredAt = Date.now();
+        this.pendingContextMessages.clear();
+        this.rejectedContextTokens.clear();
+        this.abortController?.abort();
+        const authMsg = '微信 token 已失效，通道已停止使用旧 token。请运行: ec init wechat';
+        logger.error(`[WeChat] Reauthentication required: ${error.message}`);
+        try {
+            if (this.eventBus) {
+                this.eventBus.publish({
+                    type: 'channel:error',
+                    channel: 'wechat',
+                    ...(this.channelName ? { channelName: this.channelName } : {}),
+                    status: 'auth_error',
+                    message: authMsg,
+                    timestamp: Date.now(),
+                });
+            }
+            else if (this.onSessionExpired) {
+                this.onSessionExpired(authMsg);
+            }
+        }
+        catch (notifyError) {
+            logger.error('[WeChat] Failed to publish reauthentication notice:', notifyError);
+        }
+    }
     // ── Persistence ────────────────────────────────────────────────────
     /** 持久化 context_token 到文件，供 restart-monitor 等外部进程读取 */
     persistContextTokens() {
@@ -718,6 +862,10 @@ export class WechatChannel {
     // ── Utilities ─────────────────────────────────────────────────────────
     sleep(ms, signal) {
         return new Promise((resolve, reject) => {
+            if (signal.aborted) {
+                reject(new Error('aborted'));
+                return;
+            }
             const t = setTimeout(resolve, ms);
             signal.addEventListener('abort', () => {
                 clearTimeout(t);
@@ -795,7 +943,7 @@ export class WechatChannelPlugin {
         return {
             channelType: 'wechat', adapter, channel,
             policy,
-            options: { fileMarkerPattern: /\[SEND_FILE:(?:(\w+):)?([^\]]+)\]/g, flushDelay: inst.flushDelay ?? DEFAULT_FLUSH_DELAY_SECONDS },
+            options: { fileMarkerPattern: createSendFileMarkerPattern(), flushDelay: inst.flushDelay ?? DEFAULT_FLUSH_DELAY_SECONDS },
             connect: () => channel.connect(),
             disconnect: () => channel.disconnect(),
             onProjectPathRequest: () => Promise.resolve(ctx.defaultProjectPath),