evolcore 0.0.1 → 0.0.3

package/dist/channels/wecom.js

@@ -0,0 +1,1157 @@
+import crypto from 'node:crypto';
+import { logger } from '../utils/logger.js';
+import { requireOptional } from '../utils/npm-ops.js';
+import { middleOutputModePolicy, resolveShowActivities, showActivitiesPolicy } from '../core/channel-loader.js';
+import { formatItemsAsText } from '../core/message/items-formatter.js';
+import { initWelcomeManager, sendWelcomeIfNeeded } from '../utils/welcome.js';
+import { bufferToInboundImage, sanitizeFileName, saveToUploads, validateUrl } from '../utils/media-cache.js';
+import { PersistentWecomCardStore, PersistentWecomDeduper, createWecomCardTaskId, wecomChannelDataPaths, } from './wecom-state.js';
+import { buildWecomInteractionCard, buildWecomTerminalCard, buildWecomUnknownCard, parseWecomCardResponse, } from './wecom-card.js';
+import { ContactBindCodeRegistry, } from './contact-bind-code.js';
+function wecomErrorCode(error) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const direct = error.errcode;
+    if (typeof direct === 'number')
+        return direct;
+    const responseCode = error.response?.data?.errcode;
+    return typeof responseCode === 'number' ? responseCode : undefined;
+}
+function isWecomAuthError(error) {
+    return error.code === 'WS_AUTH_FAILURE_EXHAUSTED'
+        || /^Authentication failed:/i.test(error.message);
+}
+function sanitizeWecomSdkLog(message) {
+    return message
+        .replace(/("(?:aeskey|secret)"\s*:\s*")[^"]*(")/gi, '$1<redacted>$2')
+        .replace(/("url"\s*:\s*")[^"]*(")/gi, '$1<redacted>$2')
+        .replace(/(url=)https?:\/\/\S+/gi, '$1<redacted>');
+}
+function validateWecomMediaUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error('WeCom media URL is invalid');
+    }
+    if (parsed.protocol !== 'https:')
+        throw new Error(`WeCom media URL must use HTTPS: ${parsed.protocol}`);
+    if (parsed.username || parsed.password)
+        throw new Error('WeCom media URL must not contain credentials');
+    const host = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    if (host === 'localhost'
+        || host.endsWith('.localhost')
+        || host.endsWith('.local')
+        || host === '::1'
+        || /^(?:fc|fd|fe8|fe9|fea|feb)/i.test(host)) {
+        throw new Error(`WeCom media URL rejected: local host ${host}`);
+    }
+    const validation = validateUrl(url, { allowedHosts: new Set() });
+    if (!validation.ok)
+        throw new Error(`WeCom media URL rejected: ${validation.reason}`);
+}
+function truncateUtf8Bytes(value, maxBytes) {
+    const input = Buffer.from(value, 'utf8');
+    if (input.length <= maxBytes)
+        return value;
+    let end = maxBytes;
+    while (end > 0 && (input[end] & 0xc0) === 0x80)
+        end--;
+    return input.subarray(0, end).toString('utf8');
+}
+function splitUtf8Bytes(value, maxBytes) {
+    if (!value)
+        return [];
+    const chunks = [];
+    let remaining = value;
+    while (Buffer.byteLength(remaining, 'utf8') > maxBytes) {
+        let chunk = truncateUtf8Bytes(remaining, maxBytes);
+        const paragraphBreak = chunk.lastIndexOf('\n\n');
+        const lineBreak = chunk.lastIndexOf('\n');
+        const splitAt = paragraphBreak > Math.floor(chunk.length / 2)
+            ? paragraphBreak
+            : lineBreak > Math.floor(chunk.length / 2)
+                ? lineBreak
+                : chunk.length;
+        chunk = chunk.slice(0, splitAt);
+        if (!chunk)
+            chunk = truncateUtf8Bytes(remaining, maxBytes);
+        chunks.push(chunk);
+        remaining = remaining.slice(chunk.length);
+    }
+    if (remaining)
+        chunks.push(remaining);
+    return chunks;
+}
+const wecomContactBinds = new ContactBindCodeRegistry({
+    channelType: 'wecom',
+    displayName: '企微',
+    initCommand: 'ec init wecom',
+});
+export function registerPendingWecomContactBind(req) {
+    return wecomContactBinds.register(req);
+}
+export function handlePendingWecomContactBindMessage(ctx) {
+    return wecomContactBinds.handle(ctx);
+}
+export function getPendingWecomContactBind(selfAid, channelName) {
+    return wecomContactBinds.get(selfAid, channelName);
+}
+export function clearPendingWecomContactBinds() {
+    wecomContactBinds.clear();
+}
+// ── WecomChannel ───────────────────────────────────────────────────────────────
+export class WecomChannel {
+    agentAid;
+    channelName;
+    config;
+    client = null;
+    connectionState = 'idle';
+    lastConnectionError;
+    messageHandler = null;
+    seenMessages = new Map();
+    persistentDeduper;
+    cardStore;
+    cleanupInterval = null;
+    projectPathProvider = null;
+    interactionCallback;
+    interactionInvalidationCallback;
+    channelKey;
+    cardCallbacksInFlight = new Set();
+    interactionSendTails = new Map();
+    connectPromise;
+    activeStreams = new Map();
+    // Welcome message manager
+    welcomeManager;
+    constructor(config, agentAid, channelName) {
+        this.agentAid = agentAid;
+        this.channelName = channelName;
+        this.config = config;
+        this.channelKey = channelName || `wecom#${agentAid || 'standalone'}#main`;
+        this.cardStore = new PersistentWecomCardStore(undefined, this.channelKey);
+        if (agentAid && channelName) {
+            const paths = wecomChannelDataPaths(agentAid, channelName);
+            this.persistentDeduper = new PersistentWecomDeduper(paths.dedupFile, channelName);
+            this.cardStore = new PersistentWecomCardStore(paths.cardFile, channelName);
+        }
+        // 初始化 welcomeManager（使用共享帮助函数）
+        if (agentAid && channelName) {
+            this.welcomeManager = initWelcomeManager('wecom', agentAid, channelName);
+        }
+    }
+    // ── Public helpers (testable) ─────────────────────────────────────────────
+    isDuplicate(msgId) {
+        if (this.persistentDeduper)
+            return this.persistentDeduper.checkAndMark(msgId);
+        if (this.seenMessages.has(msgId))
+            return true;
+        this.seenMessages.set(msgId, Date.now());
+        return false;
+    }
+    resolveChatId(chattype, chatid, userid) {
+        return chattype === 'group' ? (chatid || '') : userid;
+    }
+    // ── Lifecycle ─────────────────────────────────────────────────────────────
+    async connect() {
+        if (this.connectionState === 'authenticated' && this.client)
+            return;
+        if (this.connectPromise)
+            return this.connectPromise;
+        if (this.client)
+            return this.waitForAuthentication(this.client, 20_000);
+        const pending = this.connectOnce();
+        this.connectPromise = pending;
+        try {
+            await pending;
+        }
+        finally {
+            if (this.connectPromise === pending)
+                this.connectPromise = undefined;
+        }
+    }
+    async connectOnce() {
+        const { botId, secret } = this.config;
+        if (!botId || !secret) {
+            throw new Error('WeCom botId/secret not configured');
+        }
+        const sdk = await requireOptional('@wecom/aibot-node-sdk');
+        this.connectionState = 'connecting';
+        this.lastConnectionError = undefined;
+        const client = new sdk.WSClient({
+            botId,
+            secret,
+            heartbeatInterval: 30_000,
+            maxReconnectAttempts: 10,
+            maxAuthFailureAttempts: 5,
+            requestTimeout: 15_000,
+            logger: {
+                debug: (message) => logger.debug(`[WeCom SDK] ${sanitizeWecomSdkLog(message)}`),
+                info: (message, ...args) => logger.info(`[WeCom SDK] ${sanitizeWecomSdkLog(message)}`, ...args),
+                warn: (message, ...args) => logger.warn(`[WeCom SDK] ${sanitizeWecomSdkLog(message)}`, ...args),
+                error: (message, ...args) => logger.error(`[WeCom SDK] ${sanitizeWecomSdkLog(message)}`, ...args),
+            },
+        });
+        this.client = client;
+        // Message events
+        client.on('message', (frame) => {
+            if (this.client !== client)
+                return;
+            this.handleIncoming(frame).catch((err) => {
+                logger.error('[WeCom] Failed to process incoming message:', err);
+            });
+        });
+        // Event callbacks (enter_chat, etc.)
+        client.on('event.enter_chat', (frame) => {
+            if (this.client !== client)
+                return;
+            const body = frame?.body;
+            if (body) {
+                logger.debug(`[WeCom] User entered chat: userid=${body.from?.userid} chattype=${body.chattype}`);
+            }
+        });
+        // Lifecycle events
+        client.on('authenticated', () => {
+            if (this.client !== client)
+                return;
+            this.connectionState = 'authenticated';
+            this.lastConnectionError = undefined;
+            logger.info('[WeCom] WebSocket authenticated');
+        });
+        client.on('disconnected', (reason) => {
+            if (this.client !== client)
+                return;
+            logger.warn(`[WeCom] WebSocket disconnected: ${reason}`);
+            if (this.connectionState !== 'kicked')
+                this.connectionState = 'disconnected';
+            this.lastConnectionError = reason;
+            this.expireActiveStreams();
+        });
+        client.on('reconnecting', (attempt) => {
+            if (this.client !== client)
+                return;
+            this.connectionState = 'reconnecting';
+            this.expireActiveStreams();
+            logger.info(`[WeCom] Reconnecting (attempt ${attempt})...`);
+        });
+        client.on('error', (error) => {
+            if (this.client !== client)
+                return;
+            this.lastConnectionError = error.message;
+            if (isWecomAuthError(error))
+                this.connectionState = 'auth_failed';
+            else if (error.code === 'WS_RECONNECT_EXHAUSTED')
+                this.connectionState = 'disconnected';
+            logger.error('[WeCom] WebSocket error:', error);
+        });
+        client.on('event.template_card_event', (frame) => {
+            if (this.client !== client)
+                return;
+            this.handleTemplateCardEvent(frame).catch(error => {
+                logger.error('[WeCom] Failed to process template card event:', error);
+            });
+        });
+        client.on('event.disconnected_event', () => {
+            if (this.client !== client)
+                return;
+            this.connectionState = 'kicked';
+            this.lastConnectionError = 'A newer connection subscribed with the same Bot ID';
+            this.expireActiveStreams();
+            logger.error(`[WeCom] Connection kicked for channel ${this.channelKey}; another client is using this Bot ID`);
+        });
+        client.connect();
+        try {
+            await this.waitForAuthentication(client, 20_000);
+        }
+        catch (error) {
+            const wasCurrentClient = this.client === client;
+            if (wasCurrentClient)
+                this.client = null;
+            try {
+                client.disconnect();
+            }
+            catch { /* ignore */ }
+            if (wasCurrentClient) {
+                const failedState = this.connectionState;
+                if (failedState !== 'auth_failed')
+                    this.connectionState = 'disconnected';
+                this.lastConnectionError = error instanceof Error ? error.message : String(error);
+            }
+            throw error;
+        }
+        // Hourly cleanup of old dedup entries
+        this.cleanupInterval = setInterval(() => {
+            const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+            for (const [id, ts] of this.seenMessages) {
+                if (ts < cutoff)
+                    this.seenMessages.delete(id);
+            }
+            this.cleanupStreams();
+        }, 60 * 60 * 1000);
+        logger.info('[WeCom] Channel connected');
+    }
+    async disconnect() {
+        this.connectionState = 'idle';
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        const client = this.client;
+        this.client = null;
+        if (client) {
+            try {
+                client.disconnect();
+            }
+            catch { /* ignore */ }
+        }
+        this.activeStreams.clear();
+        logger.info('[WeCom] Channel disconnected');
+    }
+    onMessage(handler) {
+        this.messageHandler = handler;
+    }
+    onProjectPathRequest(provider) {
+        this.projectPathProvider = provider;
+    }
+    getStatus() {
+        return {
+            connected: this.connectionState === 'authenticated',
+            state: this.connectionState,
+            error: this.lastConnectionError,
+        };
+    }
+    async reconnect() {
+        await this.disconnect();
+        try {
+            await this.connect();
+            return '重连成功';
+        }
+        catch (err) {
+            return `重连失败: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    onInteraction(callback) {
+        this.interactionCallback = callback;
+    }
+    onInteractionInvalidated(callback) {
+        this.interactionInvalidationCallback = callback;
+    }
+    invalidateInteraction(interactionId, reason = 'cancelled') {
+        this.cardStore?.invalidateByInteractionId(interactionId, reason);
+    }
+    async withInteractionSendLock(chatId, run) {
+        const previous = this.interactionSendTails.get(chatId) ?? Promise.resolve();
+        let release;
+        const current = new Promise(resolve => { release = resolve; });
+        this.interactionSendTails.set(chatId, current);
+        await previous.catch(() => undefined);
+        try {
+            return await run();
+        }
+        finally {
+            release();
+            if (this.interactionSendTails.get(chatId) === current)
+                this.interactionSendTails.delete(chatId);
+        }
+    }
+    async invalidateSupersededCards(records) {
+        for (const record of records) {
+            if (this.interactionInvalidationCallback) {
+                try {
+                    await this.interactionInvalidationCallback(record.interaction.id, 'superseded');
+                }
+                catch (error) {
+                    logger.warn(`[WeCom] Failed to cancel superseded interaction ${record.interaction.id}: ${String(error)}`);
+                }
+            }
+            this.cardStore?.invalidateByInteractionId(record.interaction.id, 'superseded');
+        }
+    }
+    async waitForAuthentication(client, timeoutMs) {
+        if (this.connectionState === 'authenticated')
+            return;
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                client.off('authenticated', onAuthenticated);
+                client.off('error', onError);
+                client.off('disconnected', onDisconnected);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const onAuthenticated = () => finish();
+            const onError = (error) => {
+                if (isWecomAuthError(error))
+                    finish(error);
+            };
+            const onDisconnected = (reason) => finish(new Error(`WeCom disconnected before authentication: ${reason}`));
+            const timer = setTimeout(() => {
+                finish(new Error(`WeCom authentication timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            client.on('authenticated', onAuthenticated);
+            client.on('error', onError);
+            client.on('disconnected', onDisconnected);
+            if (this.connectionState === 'authenticated')
+                finish();
+        });
+    }
+    cleanupStreams(now = Date.now()) {
+        const cutoff = now - 30 * 60 * 1000;
+        for (const [reqId, stream] of this.activeStreams) {
+            if (stream.finished || stream.lastUpdatedAt < cutoff)
+                this.activeStreams.delete(reqId);
+        }
+    }
+    expireActiveStreams() {
+        for (const stream of this.activeStreams.values())
+            stream.expired = true;
+    }
+    createReplyContext(frame, chatId, messageId) {
+        const reqId = String(frame.headers?.req_id ?? '').trim();
+        const streamId = crypto.randomUUID();
+        if (reqId) {
+            this.activeStreams.set(reqId, {
+                reqId,
+                streamId,
+                frame: { headers: { ...frame.headers, req_id: reqId } },
+                chatId,
+                messageId,
+                accumulatedText: '',
+                createdAt: Date.now(),
+                lastUpdatedAt: Date.now(),
+                started: false,
+                finished: false,
+                expired: false,
+            });
+        }
+        return {
+            replyToMessageId: messageId,
+            metadata: {
+                wecomReqId: reqId,
+                wecomStreamId: streamId,
+                wecomMessageId: messageId,
+            },
+        };
+    }
+    streamFromReplyContext(replyContext) {
+        const reqId = replyContext?.metadata?.wecomReqId;
+        if (typeof reqId !== 'string' || !reqId)
+            return undefined;
+        return this.activeStreams.get(reqId);
+    }
+    requireClient() {
+        if (!this.client)
+            throw new Error('WeCom client is not connected');
+        return this.client;
+    }
+    async sendProactiveMarkdown(chatId, content) {
+        const client = this.requireClient();
+        for (const chunk of splitUtf8Bytes(content, 20_480)) {
+            await client.sendMessage(chatId, {
+                msgtype: 'markdown',
+                markdown: { content: chunk },
+            });
+        }
+    }
+    // ── Inbound message handling ──────────────────────────────────────────────
+    async handleIncoming(frame) {
+        const body = frame?.body;
+        if (!body)
+            return;
+        if (body.aibotid && body.aibotid !== this.config.botId) {
+            logger.warn(`[WeCom] Ignoring callback for unexpected Bot ID: ${body.aibotid}`);
+            return;
+        }
+        const msgId = body.msgid;
+        const chattype = body.chattype || 'single';
+        const chatid = body.chatid;
+        const userid = body.from?.userid || '';
+        const msgtype = body.msgtype;
+        // Dedup
+        if (msgId && this.isDuplicate(msgId)) {
+            logger.debug(`[WeCom] Duplicate message skipped: ${msgId}`);
+            return;
+        }
+        const channelId = this.resolveChatId(chattype, chatid, userid);
+        if (!channelId) {
+            logger.warn(`[WeCom] Ignoring ${chattype} message without a routable ${chattype === 'group' ? 'chatid' : 'userid'}`);
+            return;
+        }
+        const chatTypeNorm = chattype === 'group' ? 'group' : 'private';
+        const replyContext = this.createReplyContext(frame, channelId, msgId);
+        if (!this.messageHandler)
+            return;
+        // 首次交互欢迎消息（使用共享帮助函数）
+        await sendWelcomeIfNeeded(this.welcomeManager, userid, channelId, (id, text) => this.sendMessage(id, text), 'WeCom');
+        if (msgtype === 'text') {
+            const text = body.text?.content?.trim();
+            if (!text)
+                return;
+            const quote = await this.processQuote(body.quote, channelId);
+            const content = quote.prefix ? `${quote.prefix}\n${text}` : text;
+            await this.messageHandler({
+                channelId, content, chatType: chatTypeNorm,
+                peerId: userid, messageId: msgId,
+                images: quote.images.length > 0 ? quote.images : undefined,
+                replyContext,
+            });
+        }
+        else if (msgtype === 'image') {
+            await this.handleImageMessage(body, channelId, chatTypeNorm, userid, msgId, replyContext);
+        }
+        else if (msgtype === 'voice') {
+            const voiceText = body.voice?.content?.trim();
+            if (voiceText) {
+                await this.messageHandler({
+                    channelId, content: voiceText, chatType: chatTypeNorm,
+                    peerId: userid, messageId: msgId, replyContext,
+                });
+            }
+        }
+        else if (msgtype === 'file') {
+            await this.handleFileMessage(body, channelId, chatTypeNorm, userid, msgId, replyContext);
+        }
+        else if (msgtype === 'video') {
+            await this.handleVideoMessage(body, channelId, chatTypeNorm, userid, msgId, replyContext);
+        }
+        else if (msgtype === 'mixed') {
+            await this.handleMixedMessage(body, channelId, chatTypeNorm, userid, msgId, replyContext);
+        }
+        else {
+            await this.messageHandler({
+                channelId,
+                content: `[不支持的消息类型: ${msgtype}]`,
+                chatType: chatTypeNorm, peerId: userid, messageId: msgId, replyContext,
+            });
+        }
+    }
+    // ── Inbound media handling ────────────────────────────────────────────────
+    async downloadInboundMedia(url, aesKey) {
+        if (!this.client)
+            throw new Error('WeCom client is unavailable');
+        validateWecomMediaUrl(url);
+        const result = await this.client.downloadFile(url, aesKey);
+        const maxBytes = 20 * 1024 * 1024;
+        if (result.buffer.length > maxBytes) {
+            throw new Error(`WeCom media exceeds ${maxBytes} bytes`);
+        }
+        return result;
+    }
+    async processQuote(quote, channelId) {
+        const result = { prefix: '', images: [] };
+        if (!quote?.msgtype)
+            return result;
+        try {
+            if (quote.msgtype === 'text') {
+                const text = String(quote.text?.content ?? '').trim();
+                if (text)
+                    result.prefix = `[引用文本]\n${text}`;
+                return result;
+            }
+            if (quote.msgtype === 'voice') {
+                const text = String(quote.voice?.content ?? '').trim();
+                if (text)
+                    result.prefix = `[引用语音转写]\n${text}`;
+                return result;
+            }
+            if (quote.msgtype === 'image' && quote.image?.url) {
+                const media = await this.downloadInboundMedia(quote.image.url, quote.image.aeskey);
+                const image = await bufferToInboundImage(media.buffer, { filename: media.filename });
+                if (!image)
+                    throw new Error('引用图片格式不受支持');
+                result.images.push(image);
+                result.prefix = '[引用图片]';
+                return result;
+            }
+            if (quote.msgtype === 'file' && quote.file?.url) {
+                const media = await this.downloadInboundMedia(quote.file.url, quote.file.aeskey);
+                const fileName = sanitizeFileName(quote.file.filename || media.filename || 'quoted-file');
+                const projectPath = this.projectPathProvider
+                    ? await this.projectPathProvider(channelId)
+                    : process.cwd();
+                const saved = saveToUploads(media.buffer, fileName, projectPath);
+                result.prefix = `[引用文件: ${saved.fileName}]\n文件已保存到：${saved.filePath}\n请使用 Read 工具读取并分析文件内容。`;
+                return result;
+            }
+            if (quote.msgtype === 'mixed' && Array.isArray(quote.mixed?.msg_item)) {
+                const textParts = [];
+                for (const item of quote.mixed.msg_item) {
+                    if (item.msgtype === 'text' && item.text?.content) {
+                        textParts.push(String(item.text.content));
+                    }
+                    else if (item.msgtype === 'image' && item.image?.url) {
+                        const media = await this.downloadInboundMedia(item.image.url, item.image.aeskey);
+                        const image = await bufferToInboundImage(media.buffer, { filename: media.filename });
+                        if (image)
+                            result.images.push(image);
+                    }
+                }
+                result.prefix = `[引用图文]\n${textParts.join('')}`.trim();
+                return result;
+            }
+            result.prefix = `[引用了暂不支持的消息类型: ${quote.msgtype}]`;
+        }
+        catch (error) {
+            logger.warn(`[WeCom] Failed to process quote (${quote.msgtype}): ${String(error)}`);
+            result.prefix = `[引用内容读取失败: ${quote.msgtype}]`;
+        }
+        return result;
+    }
+    async handleImageMessage(body, channelId, chatType, peerId, msgId, replyContext) {
+        const imageUrl = body.image?.url;
+        const aeskey = body.image?.aeskey;
+        if (!imageUrl) {
+            logger.warn('[WeCom] Image message without url');
+            await this.messageHandler({
+                channelId, content: '[图片下载失败：缺少下载链接]',
+                chatType, peerId, messageId: msgId, replyContext,
+            });
+            return;
+        }
+        try {
+            const media = await this.downloadInboundMedia(imageUrl, aeskey);
+            const image = await bufferToInboundImage(media.buffer, { filename: media.filename });
+            if (image) {
+                await this.messageHandler({
+                    channelId,
+                    content: '用户发送了一张图片，请分析这张图片的内容。',
+                    chatType, peerId, messageId: msgId,
+                    images: [image], replyContext,
+                });
+            }
+            else {
+                logger.warn(`[WeCom] Image validation failed`);
+                await this.messageHandler({
+                    channelId, content: '[图片验证失败]',
+                    chatType, peerId, messageId: msgId, replyContext,
+                });
+            }
+        }
+        catch (error) {
+            logger.error('[WeCom] Failed to download image:', error);
+            await this.messageHandler({
+                channelId, content: '[图片下载失败]',
+                chatType, peerId, messageId: msgId, replyContext,
+            });
+        }
+    }
+    async handleFileMessage(body, channelId, chatType, peerId, msgId, replyContext) {
+        const fileUrl = body.file?.url;
+        const aeskey = body.file?.aeskey;
+        const callbackFileName = body.file?.filename
+            ? sanitizeFileName(body.file.filename)
+            : undefined;
+        const displayFileName = callbackFileName || 'file';
+        if (!fileUrl) {
+            logger.warn('[WeCom] File message without url');
+            await this.messageHandler({
+                channelId, content: `[文件下载失败：缺少下载链接] ${displayFileName}`,
+                chatType, peerId, messageId: msgId, replyContext,
+            });
+            return;
+        }
+        try {
+            const media = await this.downloadInboundMedia(fileUrl, aeskey);
+            const fileName = sanitizeFileName(callbackFileName || media.filename || 'file');
+            const projectPath = this.projectPathProvider
+                ? await this.projectPathProvider(channelId)
+                : process.cwd();
+            const { filePath } = saveToUploads(media.buffer, fileName, projectPath);
+            await this.messageHandler({
+                channelId,
+                content: `用户发送了文件：${fileName}\n文件已保存到：${filePath}\n请使用 Read 工具读取并分析文件内容。`,
+                chatType, peerId, messageId: msgId, replyContext,
+            });
+        }
+        catch (error) {
+            logger.error('[WeCom] Failed to download file:', error);
+            await this.messageHandler({
+                channelId, content: `[文件下载失败] ${displayFileName}`,
+                chatType, peerId, messageId: msgId, replyContext,
+            });
+        }
+    }
+    async handleVideoMessage(body, channelId, chatType, peerId, msgId, replyContext) {
+        const videoUrl = body.video?.url;
+        const aeskey = body.video?.aeskey;
+        if (!videoUrl) {
+            await this.messageHandler({
+                channelId, content: '[视频下载失败：缺少下载链接]',
+                chatType, peerId, messageId: msgId, replyContext,
+            });
+            return;
+        }
+        try {
+            const media = await this.downloadInboundMedia(videoUrl, aeskey);
+            const projectPath = this.projectPathProvider
+                ? await this.projectPathProvider(channelId)
+                : process.cwd();
+            const fileName = `video_${Date.now()}.mp4`;
+            const { filePath } = saveToUploads(media.buffer, fileName, projectPath);
+            await this.messageHandler({
+                channelId,
+                content: `用户发送了视频：${fileName}\n文件已保存到：${filePath}`,
+                chatType, peerId, messageId: msgId, replyContext,
+            });
+        }
+        catch (error) {
+            logger.error('[WeCom] Failed to download video:', error);
+            await this.messageHandler({
+                channelId, content: '[视频下载失败]',
+                chatType, peerId, messageId: msgId, replyContext,
+            });
+        }
+    }
+    async handleMixedMessage(body, channelId, chatType, peerId, msgId, replyContext) {
+        const msgItems = body.mixed?.msg_item;
+        if (!Array.isArray(msgItems)) {
+            await this.messageHandler({
+                channelId, content: '[不支持的图文混排格式]',
+                chatType, peerId, messageId: msgId, replyContext,
+            });
+            return;
+        }
+        let text = '';
+        const images = [];
+        for (const item of msgItems) {
+            if (item.msgtype === 'text' && item.text?.content) {
+                text += item.text.content;
+            }
+            else if (item.msgtype === 'image' && item.image?.url) {
+                try {
+                    const media = await this.downloadInboundMedia(item.image.url, item.image.aeskey);
+                    const image = await bufferToInboundImage(media.buffer, { filename: media.filename });
+                    if (image)
+                        images.push(image);
+                }
+                catch (error) {
+                    logger.warn('[WeCom] Failed to download mixed image:', error);
+                }
+            }
+        }
+        const prompt = text.trim() || (images.length > 0 ? '用户发送了一张图片，请分析这张图片的内容。' : '[空消息]');
+        await this.messageHandler({
+            channelId, content: prompt, chatType,
+            peerId, messageId: msgId,
+            images: images.length > 0 ? images : undefined,
+            replyContext,
+        });
+    }
+    // ── Outbound: text ────────────────────────────────────────────────────────
+    async sendMessage(chatId, content, replyContext) {
+        return this.sendStreamText(chatId, content, true, replyContext);
+    }
+    async sendStreamText(chatId, content, isFinal, replyContext) {
+        if (!content || content.trim() === '') {
+            logger.warn('[WeCom] Attempted to send empty message, skipping');
+            return;
+        }
+        const client = this.requireClient();
+        try {
+            const stream = this.streamFromReplyContext(replyContext);
+            if (stream && !stream.finished) {
+                stream.accumulatedText += content;
+                stream.lastUpdatedAt = Date.now();
+                const visibleText = truncateUtf8Bytes(stream.accumulatedText, 20_480);
+                if (!stream.expired) {
+                    try {
+                        if (isFinal) {
+                            await client.replyStream(stream.frame, stream.streamId, visibleText, true);
+                        }
+                        else {
+                            const result = await client.replyStreamNonBlocking(stream.frame, stream.streamId, visibleText, false);
+                            if (result === 'skipped')
+                                return;
+                        }
+                        stream.started = true;
+                    }
+                    catch (error) {
+                        if (wecomErrorCode(error) === 846608) {
+                            stream.expired = true;
+                            logger.warn(`[WeCom] Stream expired for reqId=${stream.reqId}; final reply will use proactive send`);
+                        }
+                        else {
+                            throw error;
+                        }
+                    }
+                }
+                if (isFinal) {
+                    stream.finished = true;
+                    if (stream.expired) {
+                        await this.sendProactiveMarkdown(chatId, stream.accumulatedText);
+                    }
+                    else {
+                        const chunks = splitUtf8Bytes(stream.accumulatedText, 20_480);
+                        for (const continuation of chunks.slice(1))
+                            await this.sendProactiveMarkdown(chatId, continuation);
+                    }
+                    logger.debug(`[WeCom] Finished stream reply reqId=${stream.reqId} chatId=${chatId}`);
+                }
+                return;
+            }
+            await this.sendProactiveMarkdown(chatId, content);
+            logger.debug(`[WeCom] Sent proactive message to ${chatId}`);
+        }
+        catch (error) {
+            logger.error(`[WeCom] sendMessage failed for ${chatId}:`, error.message);
+            throw error;
+        }
+    }
+    async finishStream(replyContext, fallbackText = '已完成') {
+        const stream = this.streamFromReplyContext(replyContext);
+        if (!stream || stream.finished)
+            return;
+        const client = this.requireClient();
+        const content = stream.accumulatedText || fallbackText;
+        if (stream.expired) {
+            stream.finished = true;
+            await this.sendProactiveMarkdown(stream.chatId, content);
+            return;
+        }
+        try {
+            await client.replyStream(stream.frame, stream.streamId, truncateUtf8Bytes(content, 20_480), true);
+            stream.finished = true;
+            stream.lastUpdatedAt = Date.now();
+            const chunks = splitUtf8Bytes(content, 20_480);
+            for (const continuation of chunks.slice(1))
+                await this.sendProactiveMarkdown(stream.chatId, continuation);
+        }
+        catch (error) {
+            if (wecomErrorCode(error) !== 846608)
+                throw error;
+            stream.expired = true;
+            stream.finished = true;
+            await this.sendProactiveMarkdown(stream.chatId, content);
+        }
+    }
+    // ── Outbound: image ───────────────────────────────────────────────────────
+    async sendImage(chatId, png, replyContext) {
+        const client = this.requireClient();
+        try {
+            const result = await client.uploadMedia(png, {
+                type: 'image',
+                filename: 'image.png',
+            });
+            const mediaId = result?.media_id;
+            if (!mediaId) {
+                throw new Error('WeCom media upload failed: no media_id');
+            }
+            const stream = this.streamFromReplyContext(replyContext);
+            if (stream && !stream.finished && !stream.started) {
+                await client.replyMedia(stream.frame, 'image', mediaId);
+                stream.finished = true;
+            }
+            else {
+                await this.finishStream(replyContext);
+                await client.sendMediaMessage(chatId, 'image', mediaId);
+            }
+            logger.debug(`[WeCom] Sent image to ${chatId}`);
+        }
+        catch (error) {
+            logger.error(`[WeCom] sendImage failed for ${chatId}:`, error.message);
+            throw error;
+        }
+    }
+    // ── Outbound: file ────────────────────────────────────────────────────────
+    async sendFile(chatId, filePath, replyContext) {
+        const client = this.requireClient();
+        try {
+            const fs = await import('fs');
+            const path = await import('path');
+            if (!fs.existsSync(filePath)) {
+                throw new Error(`WeCom file not found: ${filePath}`);
+            }
+            // Detect image files → route to sendImage
+            const header = Buffer.alloc(12);
+            const fd = fs.openSync(filePath, 'r');
+            fs.readSync(fd, header, 0, 12, 0);
+            fs.closeSync(fd);
+            const { fileTypeFromBuffer } = await import('file-type');
+            const ftype = await fileTypeFromBuffer(header);
+            if (ftype && ftype.mime.startsWith('image/')) {
+                const buf = fs.readFileSync(filePath);
+                return this.sendImage(chatId, buf, replyContext);
+            }
+            const buf = fs.readFileSync(filePath);
+            const fileName = path.basename(filePath);
+            const result = await client.uploadMedia(buf, {
+                type: 'file',
+                filename: fileName,
+            });
+            const mediaId = result?.media_id;
+            if (!mediaId) {
+                throw new Error('WeCom file upload failed: no media_id');
+            }
+            const stream = this.streamFromReplyContext(replyContext);
+            if (stream && !stream.finished && !stream.started) {
+                await client.replyMedia(stream.frame, 'file', mediaId);
+                stream.finished = true;
+            }
+            else {
+                await this.finishStream(replyContext);
+                await client.sendMediaMessage(chatId, 'file', mediaId);
+            }
+            logger.debug(`[WeCom] Sent file ${fileName} to ${chatId}`);
+        }
+        catch (error) {
+            logger.error(`[WeCom] sendFile failed for ${chatId}:`, error.message);
+            throw error;
+        }
+    }
+    async sendInteraction(chatId, interaction, replyContext) {
+        if (!this.cardStore)
+            return false;
+        return this.withInteractionSendLock(chatId, async () => {
+            const client = this.requireClient();
+            const superseded = this.cardStore.listPendingByChat(chatId)
+                .filter(record => record.interaction.id !== interaction.id);
+            const taskId = createWecomCardTaskId(this.channelKey, interaction.id);
+            const card = buildWecomInteractionCard(interaction, taskId);
+            const record = {
+                taskId,
+                interaction,
+                chatId,
+                createdAt: Date.now(),
+                updatedAt: Date.now(),
+                expiresAt: interaction.expiresAt,
+                status: 'pending',
+            };
+            const stream = this.streamFromReplyContext(replyContext);
+            try {
+                if (stream && !stream.finished) {
+                    if (stream.started) {
+                        await client.replyStreamWithCard(stream.frame, stream.streamId, truncateUtf8Bytes(stream.accumulatedText, 20_480), true, { templateCard: card });
+                        const chunks = splitUtf8Bytes(stream.accumulatedText, 20_480);
+                        for (const continuation of chunks.slice(1))
+                            await this.sendProactiveMarkdown(chatId, continuation);
+                    }
+                    else {
+                        await client.replyTemplateCard(stream.frame, card);
+                    }
+                    stream.finished = true;
+                }
+                else {
+                    await client.sendMessage(chatId, {
+                        msgtype: 'template_card',
+                        template_card: card,
+                    });
+                }
+                this.cardStore.set(record);
+                await this.invalidateSupersededCards(superseded);
+                logger.info(`[WeCom] Sent interaction card interaction=${interaction.id} taskId=${taskId}`);
+                return taskId;
+            }
+            catch (error) {
+                logger.error(`[WeCom] Failed to send interaction card ${interaction.id}: ${String(error)}`);
+                throw error;
+            }
+        });
+    }
+    async handleTemplateCardEvent(frame) {
+        const body = frame.body;
+        const client = this.client;
+        if (!body || !client || !this.cardStore)
+            return;
+        if (body.aibotid && body.aibotid !== this.config.botId) {
+            logger.warn(`[WeCom] Ignoring card callback for unexpected Bot ID: ${body.aibotid}`);
+            return;
+        }
+        const duplicate = body.msgid ? this.isDuplicate(body.msgid) : false;
+        if (duplicate)
+            logger.debug(`[WeCom] Replaying terminal response for duplicate card callback: ${body.msgid}`);
+        const rawEvent = body.event;
+        const event = (rawEvent?.template_card_event ?? rawEvent);
+        const taskId = String(event?.task_id ?? '').trim();
+        if (!taskId)
+            return;
+        const record = this.cardStore.get(taskId);
+        if (!record) {
+            logger.warn(`[WeCom] Card callback has no local record: taskId=${taskId}`);
+            await client.updateTemplateCard(frame, buildWecomUnknownCard(taskId), body.from?.userid ? [body.from.userid] : undefined);
+            return;
+        }
+        const operatorId = body.from?.userid;
+        if (record.interaction.initiatorId && operatorId !== record.interaction.initiatorId) {
+            await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'rejected'), operatorId ? [operatorId] : undefined);
+            return;
+        }
+        if (record.status !== 'pending' || (record.expiresAt && Date.now() > record.expiresAt)) {
+            const reason = record.invalidationReason || (record.status === 'resolved' ? '已处理' : '已过期');
+            await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'invalidated', reason), operatorId ? [operatorId] : undefined);
+            return;
+        }
+        if (this.cardCallbacksInFlight.has(taskId)) {
+            await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'unavailable', '正在处理'), operatorId ? [operatorId] : undefined);
+            return;
+        }
+        this.cardCallbacksInFlight.add(taskId);
+        try {
+            const parsed = parseWecomCardResponse(record, event, operatorId);
+            if (!parsed) {
+                await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'invalidated', '无法识别操作'), operatorId ? [operatorId] : undefined);
+                return;
+            }
+            if (parsed.command) {
+                if (!this.messageHandler) {
+                    await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'unavailable'), operatorId ? [operatorId] : undefined);
+                    return;
+                }
+                await this.messageHandler({
+                    channelId: record.chatId,
+                    content: parsed.command,
+                    chatType: body.chattype === 'group' ? 'group' : 'private',
+                    peerId: operatorId || '',
+                    messageId: `card-trigger-${body.msgid || Date.now()}`,
+                    source: 'card-trigger',
+                });
+                this.cardStore.resolve(taskId, parsed.command);
+                await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'resolved', parsed.command));
+                return;
+            }
+            if (!parsed.response || !this.interactionCallback) {
+                await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'unavailable'), operatorId ? [operatorId] : undefined);
+                return;
+            }
+            const accepted = (await this.interactionCallback(parsed.response)) !== false;
+            if (!accepted) {
+                const invalidated = this.cardStore.invalidateByInteractionId(record.interaction.id, 'backend_rejected') || record;
+                await client.updateTemplateCard(frame, buildWecomTerminalCard(invalidated, 'invalidated', '请求已失效'));
+                return;
+            }
+            this.cardStore.resolve(taskId, parsed.response.action);
+            await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'resolved', parsed.response.action));
+        }
+        finally {
+            this.cardCallbacksInFlight.delete(taskId);
+        }
+    }
+}
+// ── Plugin ─────────────────────────────────────────────────────────────────────
+function isValidCredential(value) {
+    return !!value && !value.includes('your-') && !value.includes('placeholder');
+}
+export class WecomChannelPlugin {
+    name = 'wecom';
+    async createInstance(inst, ctx) {
+        if (inst.enabled === false)
+            return null;
+        if (!isValidCredential(inst.botId) || !isValidCredential(inst.secret))
+            return null;
+        const channel = new WecomChannel({
+            botId: inst.botId,
+            secret: inst.secret,
+        }, ctx.agentName, inst.name);
+        const mode = resolveShowActivities(inst);
+        const adapter = {
+            channelName: inst.name,
+            channelKey: inst.name,
+            capabilities: { file: true, image: true, interaction: true, markdown: true, thought: false, status: true, thread: false, authenticatedApproval: true },
+            send: async (envelope, payload) => {
+                const channelId = envelope.channelId;
+                switch (payload.kind) {
+                    case 'result.text':
+                        await channel.sendStreamText(channelId, payload.text, payload.isFinal, envelope.replyContext);
+                        return;
+                    case 'command.result':
+                    case 'command.error':
+                    case 'system.notice':
+                    case 'system.error':
+                    case 'result.error':
+                        await channel.sendMessage(channelId, payload.text, envelope.replyContext);
+                        return;
+                    case 'result.file':
+                        await channel.sendFile(channelId, payload.filePath, envelope.replyContext);
+                        return;
+                    case 'result.image':
+                        await channel.sendImage(channelId, payload.data, envelope.replyContext);
+                        return;
+                    case 'activity.batch': {
+                        const filtered = payload.items.filter((i) => !(i.kind === 'tool_result' && i.ok));
+                        const text = formatItemsAsText(filtered);
+                        if (text)
+                            await channel.sendStreamText(channelId, text, false, envelope.replyContext);
+                        return;
+                    }
+                    case 'status.completed':
+                        await channel.finishStream(envelope.replyContext);
+                        return;
+                    case 'status.interrupted':
+                    case 'status.timeout':
+                        await channel.finishStream(envelope.replyContext, '任务已中止');
+                        return;
+                    case 'status.started':
+                    case 'status.queued':
+                    case 'status.progress': return;
+                    case 'status.requires_action':
+                        await channel.sendMessage(channelId, '等待 owner 审批', envelope.replyContext);
+                        return;
+                    case 'status.error':
+                        if (payload.metadata?.message) {
+                            await channel.sendMessage(channelId, payload.metadata.message, envelope.replyContext);
+                        }
+                        else {
+                            await channel.finishStream(envelope.replyContext, '任务执行失败');
+                        }
+                        return;
+                    case 'interaction': {
+                        try {
+                            const taskId = await channel.sendInteraction(channelId, payload.interaction, envelope.replyContext);
+                            if (taskId)
+                                return;
+                        }
+                        catch (error) {
+                            logger.warn(`[WeCom] Interaction card delivery failed, using text fallback: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                        if (payload.fallbackText) {
+                            await channel.sendMessage(channelId, payload.fallbackText, envelope.replyContext);
+                            return;
+                        }
+                        throw new Error('WeCom interaction delivery failed and no fallback text was provided');
+                    }
+                    default: return;
+                }
+            },
+            onInteraction: (callback) => channel.onInteraction(callback),
+            onInteractionInvalidated: (callback) => channel.onInteractionInvalidated(callback),
+            invalidateInteraction: (interactionId, reason) => channel.invalidateInteraction(interactionId, reason),
+        };
+        const policy = {
+            canSwitchProject: (_, identity) => identity === 'owner' || identity === 'admin',
+            canListProjects: (_, identity) => identity === 'owner' || identity === 'admin',
+            canCreateSession: () => true,
+            canDeleteSession: () => true,
+            canImportCliSession: (_, identity) => identity === 'owner' || identity === 'admin',
+            messagePrefix: (chatType, peerName) => (chatType === 'group' && peerName) ? `[${peerName}] ` : '',
+            showMiddleResult: (chatType, identity) => showActivitiesPolicy(mode, chatType, identity),
+            middleOutputMode: (chatType, identity) => middleOutputModePolicy(mode, chatType, identity),
+            showIdleMonitor: (chatType, identity) => showActivitiesPolicy(mode, chatType, identity),
+            accumulateErrors: () => true,
+        };
+        return {
+            channelType: 'wecom', adapter, channel,
+            policy,
+            options: { fileMarkerPattern: /\[SEND_FILE:(?:(\w+):)?([^\]]+)\]/g, supportsImages: true, flushDelay: inst.flushDelay },
+            connect: () => channel.connect(),
+            disconnect: () => channel.disconnect(),
+            onProjectPathRequest: () => Promise.resolve(ctx.defaultProjectPath),
+            registerBridge(bridge, channelType) {
+                bridge.register(adapter.channelName, (handler) => channel.onMessage(async (event) => {
+                    await handler({
+                        channel: adapter.channelName, channelType, channelId: event.channelId,
+                        selfAID: ctx.agentName, content: event.content, images: event.images,
+                        chatType: event.chatType || 'private', peerId: event.peerId || '',
+                        peerName: event.peerName, messageId: event.messageId,
+                        replyContext: event.replyContext,
+                        source: event.source,
+                    });
+                }), (channelId, text, replyContext) => channel.sendMessage(channelId, text, replyContext), adapter, channelType);
+            },
+        };
+    }
+}