cli-claw-kit 0.0.1

package/dist/feishu.js

@@ -0,0 +1,1628 @@
+import fs from 'fs';
+import * as fsPromises from 'node:fs/promises';
+import * as path from 'node:path';
+import * as lark from '@larksuiteoapi/node-sdk';
+import { setLastGroupSync, storeChatMetadata, storeMessageDirect, updateChatName, } from './db.js';
+import { logger } from './logger.js';
+import { saveDownloadedFile, MAX_FILE_SIZE, FileTooLargeError, } from './im-downloader.js';
+import { notifyNewImMessage } from './message-notifier.js';
+import { broadcastNewMessage } from './web.js';
+import { detectImageMimeType } from './image-detector.js';
+import { resolveJidByMessageId, getStreamingSession, } from './feishu-streaming-card.js';
+import { optimizeMarkdownStyle } from './feishu-markdown-style.js';
+// ─── Shared Helpers (pure functions, no instance state) ────────
+// Max characters per markdown element in Feishu cards
+const CARD_MD_LIMIT = 4000;
+// Feishu card allows at most 5 markdown tables; beyond this, skip card and use post+md directly
+const CARD_TABLE_LIMIT = 5;
+const FEISHU_WS_READY_STATE_OPEN = 1;
+const WS_HEALTH_CHECK_INTERVAL_MS = 15_000;
+const WS_RECONNECT_CHECK_THRESHOLD = 4;
+const WS_RECONNECT_MIN_INTERVAL_MS = 30_000;
+const BACKFILL_LOOKBACK_MS = 5 * 60 * 1000;
+const BACKFILL_PAGE_SIZE = 50;
+const BACKFILL_MAX_PAGES_PER_CHAT = 5;
+function toEpochMs(value) {
+    const numeric = typeof value === 'number' ? value : Number(value ?? 0);
+    if (!Number.isFinite(numeric) || numeric <= 0)
+        return 0;
+    return numeric < 1e12 ? Math.trunc(numeric * 1000) : Math.trunc(numeric);
+}
+/**
+ * Extract message content from Feishu message.
+ * Returns text content, optional image keys, and optional file infos for download.
+ */
+function extractMessageContent(messageType, content) {
+    // merge_forward: WebSocket 推送的内容是纯字符串 "Merged and Forwarded Message"（非 JSON），
+    // 必须在 JSON.parse 之前单独处理，否则 parse 失败导致消息被丢弃
+    if (messageType === 'merge_forward') {
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch {
+            return { text: '[合并转发消息]' };
+        }
+        const items = parsed.message_list || parsed.items || [];
+        if (!Array.isArray(items) || items.length === 0) {
+            return { text: '[合并转发消息]' };
+        }
+        const lines = ['[合并转发消息]:'];
+        for (const item of items.slice(0, 20)) {
+            const sender = item.sender_name || item.sender || '未知';
+            const body = item.body?.content || item.content || '';
+            let text = '';
+            try {
+                const subType = item.msg_type || item.message_type || 'text';
+                const sub = extractMessageContent(subType, body);
+                text = sub.text || '';
+            }
+            catch {
+                text = typeof body === 'string' ? body : '';
+            }
+            if (text) {
+                lines.push(`> ${sender}: ${text.split('\n')[0].slice(0, 200)}`);
+            }
+        }
+        if (items.length > 20) {
+            lines.push(`> ... 共 ${items.length} 条消息`);
+        }
+        return { text: lines.join('\n') };
+    }
+    try {
+        const parsed = JSON.parse(content);
+        if (messageType === 'text') {
+            return { text: parsed.text || '' };
+        }
+        if (messageType === 'post') {
+            // Extract text and inline images from rich post content.
+            const lines = [];
+            const imageKeys = [];
+            // 飞书 post 消息有三种已知格式：
+            // 1. 带 post + 语言包裹：{"post": {"zh_cn": {"title": "...", "content": [[...]]}}}
+            // 2. 仅语言包裹：{"zh_cn": {"title": "...", "content": [[...]]}}
+            // 3. 无包裹（直接 title+content）：{"title": "...", "content": [[...]]}
+            const post = parsed.post || parsed;
+            if (!post || typeof post !== 'object') {
+                logger.warn({ keys: Object.keys(parsed) }, 'Empty post object in post message');
+                return { text: '' };
+            }
+            // 判断 contentData：如果 post 本身就有 content 数组，直接用；否则查找语言层
+            let contentData;
+            if (Array.isArray(post.content)) {
+                // 格式 3：无包裹，post 本身就是 {title, content}
+                contentData = post;
+                logger.debug('Post message using flat format (no locale wrapper)');
+            }
+            else {
+                // 格式 1/2：有语言层包裹
+                contentData = post.zh_cn || post.en_us || Object.values(post)[0];
+            }
+            if (!contentData || !Array.isArray(contentData.content)) {
+                logger.warn({ keys: Object.keys(post) }, 'Missing content array in post message');
+                return { text: '' };
+            }
+            // Include post title if present
+            if (contentData.title && typeof contentData.title === 'string') {
+                lines.push(contentData.title);
+            }
+            for (const paragraph of contentData.content) {
+                // Handle both array paragraphs and flat object segments
+                const segments = Array.isArray(paragraph)
+                    ? paragraph
+                    : paragraph && typeof paragraph === 'object'
+                        ? [paragraph]
+                        : null;
+                if (!segments)
+                    continue;
+                const parts = [];
+                for (const segment of segments) {
+                    if (!segment || typeof segment !== 'object')
+                        continue;
+                    if (segment.tag === 'text' && typeof segment.text === 'string') {
+                        parts.push(segment.text);
+                    }
+                    else if (segment.tag === 'a' && typeof segment.text === 'string') {
+                        parts.push(segment.text);
+                    }
+                    else if (segment.tag === 'at') {
+                        const mentionName = typeof segment.user_name === 'string'
+                            ? segment.user_name
+                            : typeof segment.text === 'string'
+                                ? segment.text
+                                : typeof segment.name === 'string'
+                                    ? segment.name
+                                    : '用户';
+                        parts.push(`@${mentionName}`);
+                    }
+                    else if (segment.tag === 'img' &&
+                        typeof segment.image_key === 'string') {
+                        imageKeys.push(segment.image_key);
+                        parts.push('[图片]');
+                    }
+                    else if (segment.tag === 'media') {
+                        parts.push('[视频]');
+                    }
+                    else if (segment.tag === 'emotion' &&
+                        typeof segment.emoji_type === 'string') {
+                        parts.push(`:${segment.emoji_type}:`);
+                    }
+                    else if (typeof segment.text === 'string') {
+                        parts.push(segment.text);
+                    }
+                }
+                if (parts.length > 0)
+                    lines.push(parts.join(''));
+            }
+            return {
+                text: lines.join('\n'),
+                imageKeys: imageKeys.length > 0 ? imageKeys : undefined,
+            };
+        }
+        if (messageType === 'image') {
+            const imageKey = parsed.image_key;
+            if (imageKey) {
+                return { text: '', imageKeys: [imageKey] };
+            }
+        }
+        if (messageType === 'file') {
+            const fileKey = parsed.file_key;
+            const filename = parsed.file_name || '';
+            if (fileKey) {
+                return {
+                    text: `[文件: ${filename || fileKey}]`,
+                    fileInfos: [{ fileKey, filename }],
+                };
+            }
+        }
+        if (messageType === 'sticker') {
+            const stickerDesc = parsed.description || parsed.sticker_id || '表情包';
+            return { text: `[表情包: ${stickerDesc}]` };
+        }
+        if (messageType === 'audio') {
+            const duration = parsed.duration
+                ? `${Math.round(parsed.duration / 1000)}s`
+                : '';
+            return { text: `[语音消息${duration ? ': ' + duration : ''}]` };
+        }
+        if (messageType === 'share_chat') {
+            const chatName = parsed.chat_name || parsed.chat_id || '未知群聊';
+            return { text: `[分享群聊: ${chatName}]` };
+        }
+        if (messageType === 'share_user') {
+            const userName = parsed.user_name || parsed.user_id || '未知用户';
+            return { text: `[分享用户: ${userName}]` };
+        }
+        if (messageType === 'system') {
+            const body = parsed.body || parsed.content || '';
+            const systemText = typeof body === 'string' ? body : JSON.stringify(body);
+            return { text: `[系统消息: ${systemText.slice(0, 200)}]` };
+        }
+        if (messageType === 'interactive') {
+            // Extract title and text elements from interactive card messages
+            const parts = [];
+            if (parsed.title) {
+                parts.push(parsed.title);
+            }
+            if (Array.isArray(parsed.elements)) {
+                for (const row of parsed.elements) {
+                    if (!Array.isArray(row))
+                        continue;
+                    for (const el of row) {
+                        if (!el || typeof el !== 'object')
+                            continue;
+                        if (el.tag === 'text' && typeof el.text === 'string') {
+                            parts.push(el.text);
+                        }
+                        else if (el.tag === 'a' && typeof el.text === 'string') {
+                            parts.push(`[${el.text}](${el.href || ''})`);
+                        }
+                        else if (el.tag === 'note' && Array.isArray(el.elements)) {
+                            const noteText = el.elements
+                                .filter((n) => n.tag === 'text' && typeof n.text === 'string')
+                                .map((n) => n.text)
+                                .join('');
+                            if (noteText)
+                                parts.push(noteText);
+                        }
+                        // Skip buttons, hr, select_static, img — not useful as text
+                    }
+                }
+            }
+            const cardText = parts.filter(Boolean).join('\n');
+            return { text: cardText || '[飞书卡片消息]' };
+        }
+        if (messageType === 'media') {
+            return { text: '[视频消息]' };
+        }
+        if (messageType === 'location') {
+            return {
+                text: `[位置: ${parsed.name || parsed.address || '未知位置'}]`,
+            };
+        }
+        if (messageType === 'share_calendar_event') {
+            return {
+                text: `[日程分享: ${parsed.summary || parsed.event_id || ''}]`,
+            };
+        }
+        if (messageType === 'video_chat') {
+            return { text: `[视频会议: ${parsed.topic || ''}]` };
+        }
+        if (messageType === 'todo') {
+            return {
+                text: `[待办: ${parsed.task_id || parsed.summary || ''}]`,
+            };
+        }
+        if (messageType === 'hongbao') {
+            return { text: '[红包消息]' };
+        }
+        // 未知消息类型：返回类型占位符，避免静默丢弃
+        return { text: `[${messageType}]` };
+    }
+    catch (err) {
+        logger.warn({ err, messageType, content }, 'Failed to parse message content');
+        return { text: `[${messageType}]` };
+    }
+}
+/**
+ * Split long text at paragraph boundaries to fit within card element limits.
+ */
+function splitAtParagraphs(text, maxLen) {
+    if (text.length <= maxLen)
+        return [text];
+    const chunks = [];
+    let remaining = text;
+    while (remaining.length > maxLen) {
+        // Prefer splitting at double newline (paragraph break)
+        let idx = remaining.lastIndexOf('\n\n', maxLen);
+        if (idx < maxLen * 0.3) {
+            // Fallback to single newline
+            idx = remaining.lastIndexOf('\n', maxLen);
+        }
+        if (idx < maxLen * 0.3) {
+            // Hard split as last resort
+            idx = maxLen;
+        }
+        chunks.push(remaining.slice(0, idx).trim());
+        remaining = remaining.slice(idx).trim();
+    }
+    if (remaining)
+        chunks.push(remaining);
+    return chunks;
+}
+/**
+ * Map file extension to Feishu file type.
+ */
+function getFileType(ext) {
+    const map = {
+        '.pdf': 'pdf',
+        '.doc': 'doc',
+        '.docx': 'doc',
+        '.xls': 'xls',
+        '.xlsx': 'xls',
+        '.ppt': 'ppt',
+        '.pptx': 'ppt',
+        '.mp4': 'mp4',
+        '.opus': 'opus',
+    };
+    return map[ext.toLowerCase()] || 'stream';
+}
+/**
+ * Build a Feishu interactive card (Schema 2.0) from markdown text.
+ * Applies optimizeMarkdownStyle() for proper rendering in Feishu cards:
+ * - Heading demotion (H1→H4, H2~H6→H5)
+ * - Code block / table spacing with <br>
+ * - Invalid image cleanup
+ */
+/** Build a post+md fallback content string for when interactive card send fails. */
+function buildPostMdFallback(text) {
+    return JSON.stringify({
+        zh_cn: {
+            content: [[{ tag: 'md', text: optimizeMarkdownStyle(text, 1) }]],
+        },
+    });
+}
+function buildInteractiveCard(text) {
+    const optimized = optimizeMarkdownStyle(text, 2);
+    const lines = text.split('\n');
+    let title = '';
+    let bodyStartIdx = 0;
+    // Extract title from first heading if present (use original text for title)
+    for (let i = 0; i < lines.length; i++) {
+        if (!lines[i].trim())
+            continue;
+        if (/^#{1,3}\s+/.test(lines[i])) {
+            title = lines[i].replace(/^#+\s*/, '').trim();
+            bodyStartIdx = i + 1;
+        }
+        break;
+    }
+    // Apply optimizeMarkdownStyle to body (title was already extracted from original)
+    const optimizedLines = optimized.split('\n');
+    // Skip lines corresponding to the title in optimized text
+    let optimizedBody;
+    if (bodyStartIdx > 0) {
+        // Find the first non-empty line in optimized text and skip it (it's the demoted title)
+        let skipIdx = 0;
+        for (let i = 0; i < optimizedLines.length; i++) {
+            if (!optimizedLines[i].trim())
+                continue;
+            skipIdx = i + 1;
+            break;
+        }
+        optimizedBody = optimizedLines.slice(skipIdx).join('\n').trim();
+    }
+    else {
+        optimizedBody = optimized.trim();
+    }
+    // Generate title if no heading found — use first line preview
+    if (!title) {
+        const firstLine = (lines.find((l) => l.trim()) || '')
+            .replace(/[*_`#\[\]]/g, '')
+            .trim();
+        title =
+            firstLine.length > 40
+                ? firstLine.slice(0, 37) + '...'
+                : firstLine || 'Reply';
+    }
+    // Build card elements
+    const elements = [];
+    const contentToRender = optimizedBody || optimized.trim();
+    if (contentToRender.length > CARD_MD_LIMIT) {
+        // Long content: split into multiple markdown elements
+        const chunks = splitAtParagraphs(contentToRender, CARD_MD_LIMIT);
+        for (const chunk of chunks) {
+            elements.push({ tag: 'markdown', content: chunk });
+        }
+    }
+    else if (contentToRender) {
+        // Split by horizontal rules for visual sections
+        const sections = contentToRender.split(/\n-{3,}\n/);
+        for (let i = 0; i < sections.length; i++) {
+            if (i > 0)
+                elements.push({ tag: 'hr' });
+            const s = sections[i].trim();
+            if (s)
+                elements.push({ tag: 'markdown', content: s });
+        }
+    }
+    // Ensure at least one element
+    if (elements.length === 0) {
+        elements.push({ tag: 'markdown', content: optimized.trim() });
+    }
+    return {
+        schema: '2.0',
+        config: {
+            wide_screen_mode: true,
+            summary: { content: title },
+        },
+        header: {
+            title: { tag: 'plain_text', content: title },
+            template: 'indigo',
+        },
+        body: { elements },
+    };
+}
+// ─── Factory Function ──────────────────────────────────────────
+/**
+ * Create an independent Feishu connection instance.
+ * Each instance manages its own client, WebSocket, and state maps.
+ */
+export function createFeishuConnection(config) {
+    // LRU deduplication cache
+    const MSG_DEDUP_MAX = 1000;
+    const MSG_DEDUP_TTL = 30 * 60 * 1000; // 30min
+    // Per-instance state
+    const msgCache = new Map();
+    const senderNameCache = new Map();
+    const lastMessageIdByChat = new Map();
+    const ackReactionByChat = new Map();
+    const typingReactionByChat = new Map();
+    const knownChatIds = new Set();
+    const chatTypeById = new Map(); // chatId → 'group' | 'p2p'
+    const lastCreateTimeByChat = new Map();
+    let client = null;
+    let wsClient = null;
+    let eventDispatcher = null;
+    let connectOptions = null;
+    let botOpenId = '';
+    let reconnecting = false;
+    let backfillRunning = false;
+    let reconnectRequestedAt = 0;
+    let lastWsStateConnected = false;
+    let disconnectedChecks = 0;
+    let disconnectedSince = null;
+    let healthTimer = null;
+    function rememberChatProgress(chatId, createTimeMs, chatType) {
+        knownChatIds.add(chatId);
+        if (chatType)
+            chatTypeById.set(chatId, chatType);
+        const prev = lastCreateTimeByChat.get(chatId) || 0;
+        if (createTimeMs > prev) {
+            lastCreateTimeByChat.set(chatId, createTimeMs);
+        }
+    }
+    /**
+     * 通过访问飞书 SDK 的私有属性（wsConfig、isConnecting）获取 WebSocket 连接状态。
+     *
+     * 注意事项：
+     * 1. 该函数依赖 @larksuiteoapi/node-sdk 内部未公开的属性结构，SDK 版本升级可能导致失效
+     * 2. 失效时函数会静默降级（捕获异常后返回 null），健康检查将跳过状态判断，不会触发误重连
+     * 3. 后续可考虑使用 SDK 公开 API getReconnectInfo() 替代私有属性访问
+     */
+    function getWsConnectionState() {
+        const rawClient = wsClient;
+        try {
+            const wsInstance = rawClient.wsConfig?.getWSInstance?.();
+            const reconnectInfo = rawClient.getReconnectInfo?.() || {};
+            return {
+                connected: wsInstance?.readyState === FEISHU_WS_READY_STATE_OPEN,
+                isConnecting: rawClient.isConnecting === true,
+                nextConnectTime: Number(reconnectInfo.nextConnectTime || 0),
+            };
+        }
+        catch (err) {
+            logger.debug({ err }, 'Failed to inspect Feishu WebSocket state');
+            return null;
+        }
+    }
+    function stopHealthMonitor() {
+        if (healthTimer) {
+            clearInterval(healthTimer);
+            healthTimer = null;
+        }
+    }
+    function startHealthMonitor() {
+        stopHealthMonitor();
+        healthTimer = setInterval(() => {
+            void checkConnectionHealth();
+        }, WS_HEALTH_CHECK_INTERVAL_MS);
+        healthTimer.unref?.();
+    }
+    function isDuplicate(msgId) {
+        const now = Date.now();
+        // Map preserves insertion order; stop at first non-expired entry
+        for (const [id, ts] of msgCache.entries()) {
+            if (now - ts > MSG_DEDUP_TTL) {
+                msgCache.delete(id);
+            }
+            else {
+                break;
+            }
+        }
+        if (msgCache.size >= MSG_DEDUP_MAX) {
+            const firstKey = msgCache.keys().next().value;
+            if (firstKey)
+                msgCache.delete(firstKey);
+        }
+        return msgCache.has(msgId);
+    }
+    function markSeen(msgId) {
+        msgCache.delete(msgId);
+        msgCache.set(msgId, Date.now());
+    }
+    async function downloadFeishuImage(messageId, fileKey) {
+        try {
+            const res = await client.im.messageResource.get({
+                path: {
+                    message_id: messageId,
+                    file_key: fileKey,
+                },
+                params: {
+                    type: 'image',
+                },
+            });
+            const stream = res.getReadableStream();
+            const chunks = [];
+            for await (const chunk of stream) {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            }
+            const buffer = Buffer.concat(chunks);
+            if (buffer.length === 0) {
+                logger.warn({ messageId, fileKey }, 'Empty response from image download');
+                return null;
+            }
+            const mimeType = detectImageMimeType(buffer);
+            return {
+                base64: buffer.toString('base64'),
+                mimeType,
+            };
+        }
+        catch (err) {
+            logger.warn({ err, messageId, fileKey }, 'Failed to download Feishu image');
+            return null;
+        }
+    }
+    /**
+     * 下载飞书文件（type='file'）到工作区磁盘。
+     * 返回工作区相对路径（如 downloads/feishu/2026-03-01/report.pdf），失败返回 null。
+     */
+    async function downloadFeishuFileToDisk(messageId, fileKey, filename, groupFolder) {
+        try {
+            const res = await client.im.messageResource.get({
+                path: {
+                    message_id: messageId,
+                    file_key: fileKey,
+                },
+                params: {
+                    type: 'file',
+                },
+            });
+            const stream = res.getReadableStream();
+            const chunks = [];
+            let totalSize = 0;
+            for await (const chunk of stream) {
+                const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                totalSize += buf.length;
+                if (totalSize > MAX_FILE_SIZE) {
+                    logger.warn({ messageId, fileKey, totalSize }, 'File exceeds MAX_FILE_SIZE during download');
+                    return null;
+                }
+                chunks.push(buf);
+            }
+            const buffer = Buffer.concat(chunks);
+            if (buffer.length === 0) {
+                logger.warn({ messageId, fileKey }, 'Empty response from file download');
+                return null;
+            }
+            const effectiveName = filename || `file_${fileKey}`;
+            try {
+                const relPath = await saveDownloadedFile(groupFolder, 'feishu', effectiveName, buffer);
+                return relPath;
+            }
+            catch (err) {
+                if (err instanceof FileTooLargeError) {
+                    logger.warn({ fileKey, filename }, 'Feishu file too large, skipping');
+                    return null;
+                }
+                throw err;
+            }
+        }
+        catch (err) {
+            logger.warn({ err, messageId, fileKey }, 'Failed to download Feishu file to disk');
+            return null;
+        }
+    }
+    function getSenderName(openId) {
+        return senderNameCache.get(openId) || openId;
+    }
+    async function addReaction(messageId, emojiType) {
+        try {
+            const res = (await client.im.messageReaction.create({
+                path: { message_id: messageId },
+                data: {
+                    reaction_type: { emoji_type: emojiType },
+                },
+            }));
+            return res.data?.reaction_id || null;
+        }
+        catch (err) {
+            logger.debug({ err, messageId, emojiType }, 'Failed to add reaction');
+            return null;
+        }
+    }
+    async function removeReaction(messageId, reactionId) {
+        try {
+            await client.im.messageReaction.delete({
+                path: { message_id: messageId, reaction_id: reactionId },
+            });
+        }
+        catch (err) {
+            logger.debug({ err, messageId, reactionId }, 'Failed to remove reaction');
+        }
+    }
+    async function sendTextToChat(chatId, text) {
+        if (!client)
+            return;
+        try {
+            const receive_id_type = chatId.startsWith('oc_') ? 'chat_id' : 'open_id';
+            await client.im.v1.message.create({
+                params: { receive_id_type },
+                data: {
+                    receive_id: chatId,
+                    msg_type: 'text',
+                    content: JSON.stringify({ text }),
+                },
+            });
+        }
+        catch (err) {
+            logger.error({ chatId, err }, 'Failed to send Feishu text reply');
+        }
+    }
+    async function handleIncomingMessage(payload, source) {
+        const { onNewChat, ignoreMessagesBefore, onCommand, resolveGroupFolder, resolveEffectiveChatJid, onAgentMessage, shouldProcessGroupMessage, } = connectOptions || {};
+        const { chatId, messageId, createTimeMs, messageType, content: rawContent, mentions, chatType, senderOpenId = '', senderName, } = payload;
+        if (!chatId || !messageId)
+            return;
+        if (isDuplicate(messageId)) {
+            logger.debug({ messageId }, 'Duplicate message, skipping');
+            return;
+        }
+        markSeen(messageId);
+        logger.info({ messageId, messageType, chatId, source }, 'Feishu message received');
+        if (ignoreMessagesBefore &&
+            createTimeMs > 0 &&
+            createTimeMs < ignoreMessagesBefore) {
+            logger.info({
+                messageId,
+                createTime: createTimeMs,
+                threshold: ignoreMessagesBefore,
+            }, 'Skipping stale Feishu message from before reconnection');
+            return;
+        }
+        const extracted = extractMessageContent(messageType, rawContent);
+        let text = extracted.text;
+        if (!text?.trim() && !extracted.imageKeys && !extracted.fileInfos?.length) {
+            logger.info({ messageId, messageType }, 'No text or image content, skipping');
+            return;
+        }
+        if (mentions && Array.isArray(mentions)) {
+            for (const mention of mentions) {
+                if (mention.key) {
+                    text = text.replace(mention.key, `@${mention.name || ''}`);
+                }
+            }
+        }
+        const chatJid = `feishu:${chatId}`;
+        const resolvedSenderName = senderName || getSenderName(senderOpenId);
+        const resolvedChatName = chatType === 'p2p' ? '飞书私聊' : '飞书群聊';
+        // 先注册会话，确保 resolveGroupFolder 能正确解析 folder（含首条文件消息场景）
+        onNewChat?.(chatJid, resolvedChatName);
+        let attachmentsJson;
+        if (extracted.imageKeys && extracted.imageKeys.length > 0) {
+            // 图片消息：下载后双轨处理
+            // 1. Vision 通道：base64 附件供模型看图
+            // 2. 存盘通道：写入工作区文件，agent 可直接操作（压缩、发送等）
+            const attachments = [];
+            const groupFolder = resolveGroupFolder?.(chatJid);
+            const savedPaths = [];
+            for (const imageKey of extracted.imageKeys) {
+                const imageData = await downloadFeishuImage(messageId, imageKey);
+                if (!imageData)
+                    continue;
+                // Vision 附件
+                attachments.push({
+                    type: 'image',
+                    data: imageData.base64,
+                    mimeType: imageData.mimeType,
+                });
+                // 存盘：扩展名从 mimeType 推断，对齐文件消息处理逻辑
+                if (groupFolder) {
+                    const extMap = {
+                        'image/jpeg': '.jpg',
+                        'image/png': '.png',
+                        'image/gif': '.gif',
+                        'image/webp': '.webp',
+                        'image/bmp': '.bmp',
+                        'image/tiff': '.tiff',
+                    };
+                    const ext = extMap[imageData.mimeType] ?? '.jpg';
+                    const fileName = `feishu_img_${imageKey.slice(-8)}${ext}`;
+                    try {
+                        const relPath = await saveDownloadedFile(groupFolder, 'feishu', fileName, Buffer.from(imageData.base64, 'base64'));
+                        if (relPath)
+                            savedPaths.push(relPath);
+                    }
+                    catch (err) {
+                        logger.warn({ err, imageKey }, 'Failed to save Feishu image to disk');
+                    }
+                }
+            }
+            if (attachments.length > 0) {
+                attachmentsJson = JSON.stringify(attachments);
+                // 在 content 中添加图片标记 + 磁盘路径，与文件消息保持一致
+                // agent 可通过路径直接操作文件，无需从 DB 解码 base64
+                const pathHints = savedPaths.map((p) => `[图片: ${p}]`).join('\n');
+                const imgMarker = pathHints || '[图片]';
+                text = text ? `${imgMarker}\n${text}` : imgMarker;
+            }
+        }
+        else if (extracted.fileInfos && extracted.fileInfos.length > 0) {
+            // 文件消息：下载到磁盘，路径内联替换
+            logger.info({
+                chatJid,
+                messageId,
+                messageType,
+                fileCount: extracted.fileInfos.length,
+            }, 'Processing Feishu file download');
+            const groupFolder = resolveGroupFolder?.(chatJid);
+            if (!groupFolder) {
+                logger.warn({ chatJid }, 'Cannot resolve group folder for file download');
+                for (const fi of extracted.fileInfos) {
+                    const placeholder = `[文件: ${fi.filename || fi.fileKey}]`;
+                    text = text.replace(placeholder, `[文件下载失败: ${fi.filename || fi.fileKey}]`);
+                }
+            }
+            else {
+                for (const fi of extracted.fileInfos) {
+                    const relPath = await downloadFeishuFileToDisk(messageId, fi.fileKey, fi.filename, groupFolder);
+                    const placeholder = `[文件: ${fi.filename || fi.fileKey}]`;
+                    text = text.replace(placeholder, relPath
+                        ? `[文件: ${relPath}]`
+                        : `[文件下载失败: ${fi.filename || fi.fileKey}]`);
+                }
+            }
+        }
+        lastMessageIdByChat.set(chatId, messageId);
+        const resolvedCreateTimeMs = createTimeMs > 0 ? createTimeMs : Date.now();
+        const timestamp = new Date(resolvedCreateTimeMs).toISOString();
+        rememberChatProgress(chatId, resolvedCreateTimeMs, chatType);
+        // ── 斜杠指令：拦截已知 /xxx 命令，不进入消息流 ──
+        // 群聊中 @机器人 后跟斜杠命令，mention 替换后文本为 "@botname /cmd"，
+        // 需要先 strip 掉开头的 @mention 前缀再匹配
+        const textForSlash = text?.trim().replace(/^@\S+\s+/, '') ?? '';
+        const slashMatch = textForSlash.match(/^\/(\S+)(.*)$/);
+        if (slashMatch && onCommand) {
+            const cmdBody = (slashMatch[1] + slashMatch[2]).trim();
+            logger.info({ chatJid, cmd: slashMatch[1], cmdBody }, 'Feishu slash command detected');
+            try {
+                const reply = await onCommand(chatJid, cmdBody);
+                logger.info({
+                    chatJid,
+                    cmd: slashMatch[1],
+                    hasReply: !!reply,
+                    replyLen: reply?.length,
+                }, 'Feishu slash command processed');
+                if (reply) {
+                    await sendTextToChat(chatId, reply);
+                    return; // 已知命令，拦截
+                }
+                // reply 为 null 表示未知命令，继续作为普通消息处理
+            }
+            catch (err) {
+                logger.error({ chatJid, cmd: slashMatch[1], err }, 'Feishu slash command failed');
+                try {
+                    await sendTextToChat(chatId, '⚠️ 命令执行失败，请稍后重试');
+                }
+                catch (sendErr) {
+                    logger.error({ chatJid, sendErr }, 'Failed to send slash command error feedback');
+                }
+                return;
+            }
+        }
+        // ── 群聊 Mention 过滤：require_mention 模式下，bot 未被 @ 则丢弃 ──
+        if (chatType === 'group' && shouldProcessGroupMessage) {
+            const isBotMentioned = botOpenId
+                ? (mentions?.some((m) => m.id?.open_id === botOpenId) ?? false)
+                : true; // 无 bot open_id 时默认放行（安全降级）
+            if (!isBotMentioned && !shouldProcessGroupMessage(chatJid)) {
+                logger.debug({ chatJid, messageId }, 'Dropped group message: mention required but bot not mentioned');
+                return;
+            }
+        }
+        // ── Ack Reaction：确认已收到消息（在 mention 过滤之后，避免对未处理的消息加表情） ──
+        if (source === 'ws') {
+            addReaction(messageId, 'OnIt')
+                .then((reactionId) => {
+                if (reactionId) {
+                    ackReactionByChat.set(chatId, `${messageId}:${reactionId}`);
+                }
+            })
+                .catch(() => { });
+        }
+        // Store message and broadcast to WebSocket clients
+        const agentRouting = resolveEffectiveChatJid?.(chatJid);
+        const targetJid = agentRouting?.effectiveJid ?? chatJid;
+        const targetAgentId = agentRouting?.agentId;
+        storeChatMetadata(targetJid, timestamp);
+        storeMessageDirect(messageId, targetJid, senderOpenId, resolvedSenderName, text, timestamp, false, { attachments: attachmentsJson, sourceJid: chatJid });
+        broadcastNewMessage(targetJid, {
+            id: messageId,
+            chat_jid: targetJid,
+            source_jid: chatJid,
+            sender: senderOpenId,
+            sender_name: resolvedSenderName,
+            content: text,
+            timestamp,
+            attachments: attachmentsJson,
+        }, targetAgentId ?? undefined);
+        notifyNewImMessage();
+        if (agentRouting && agentRouting.agentId) {
+            onAgentMessage?.(chatJid, agentRouting.agentId);
+            logger.info({
+                chatJid,
+                effectiveJid: targetJid,
+                agentId: targetAgentId,
+                sender: resolvedSenderName,
+                messageId,
+                source,
+            }, 'Feishu message routed to conversation agent');
+        }
+        else if (agentRouting) {
+            // Routed to workspace main conversation (no agentId)
+            logger.info({
+                chatJid,
+                effectiveJid: targetJid,
+                sender: resolvedSenderName,
+                messageId,
+                source,
+            }, 'Feishu message routed to workspace main conversation');
+        }
+        else {
+            logger.info({ chatJid, sender: resolvedSenderName, messageId, source }, 'Feishu message stored');
+        }
+    }
+    async function backfillChatMessages(chatId, sinceMs) {
+        if (!client)
+            return;
+        const nowSec = Math.floor(Date.now() / 1000);
+        const startSec = Math.max(0, Math.floor(sinceMs / 1000));
+        const params = {
+            container_id_type: 'chat',
+            container_id: chatId,
+            sort_type: 'ByCreateTimeDesc',
+            start_time: String(startSec),
+            end_time: String(nowSec),
+            page_size: BACKFILL_PAGE_SIZE,
+        };
+        let pages = 0;
+        while (pages < BACKFILL_MAX_PAGES_PER_CHAT) {
+            const response = (await client.im.v1.message.list({ params }));
+            const list = response.data?.items || [];
+            const messages = list
+                .filter((item) => {
+                if (item.deleted === true || !item.message_id)
+                    return false;
+                // 过滤 Bot 自身发送的消息，避免 backfill 将回复当作新消息处理
+                const senderType = item.sender?.sender_type;
+                if (senderType === 'app')
+                    return false;
+                return true;
+            })
+                .map((item) => {
+                const senderOpenId = item.sender?.sender_id?.open_id || item.sender?.id || '';
+                return {
+                    chatId,
+                    messageId: item.message_id,
+                    createTimeMs: toEpochMs(item.create_time),
+                    messageType: item.msg_type || item.message_type || '',
+                    content: item.body?.content || item.content || '',
+                    chatType: item.chat_type || chatTypeById.get(chatId) || 'group',
+                    mentions: item.mentions,
+                    senderOpenId,
+                };
+            })
+                .sort((a, b) => a.createTimeMs - b.createTimeMs);
+            for (const message of messages) {
+                await handleIncomingMessage(message, 'backfill');
+            }
+            pages++;
+            if (!response.data?.has_more || !response.data.page_token) {
+                break;
+            }
+            params.page_token = response.data.page_token;
+        }
+    }
+    async function runBackfill(reason) {
+        if (!client || backfillRunning)
+            return;
+        const chatIds = Array.from(knownChatIds);
+        if (chatIds.length === 0)
+            return;
+        backfillRunning = true;
+        try {
+            const recoveredFrom = disconnectedSince ?? Date.now();
+            for (const chatId of chatIds) {
+                const lastSeen = lastCreateTimeByChat.get(chatId) || 0;
+                const baseTs = lastSeen > 0 ? lastSeen : recoveredFrom;
+                const sinceMs = Math.max(0, baseTs - BACKFILL_LOOKBACK_MS);
+                try {
+                    await backfillChatMessages(chatId, sinceMs);
+                }
+                catch (err) {
+                    logger.warn({ err, chatId, reason }, 'Feishu chat backfill failed');
+                }
+            }
+            logger.info({ reason, chatCount: chatIds.length }, 'Feishu backfill finished');
+        }
+        finally {
+            backfillRunning = false;
+        }
+    }
+    async function reconnectWebSocket(reason) {
+        if (reconnecting || !connectOptions)
+            return;
+        reconnecting = true;
+        reconnectRequestedAt = Date.now();
+        disconnectedChecks = 0;
+        try {
+            if (!eventDispatcher) {
+                logger.warn({ reason }, 'Skip Feishu reconnect: event dispatcher is missing');
+                return;
+            }
+            if (wsClient) {
+                try {
+                    await wsClient.close();
+                }
+                catch (err) {
+                    logger.debug({ err }, 'Error closing stale Feishu WS client before reconnect');
+                }
+            }
+            wsClient = new lark.WSClient({
+                appId: config.appId,
+                appSecret: config.appSecret,
+                loggerLevel: lark.LoggerLevel.info,
+            });
+            await wsClient.start({ eventDispatcher });
+            lastWsStateConnected = true;
+            logger.info({ reason }, 'Feishu WebSocket reconnected');
+            connectOptions.onReady();
+            // 先执行 backfill（需要读取 disconnectedSince 确定回填起点），完成后再重置
+            await runBackfill('reconnect');
+            disconnectedSince = null;
+        }
+        catch (err) {
+            logger.error({ err, reason }, 'Feishu WebSocket reconnect failed');
+        }
+        finally {
+            reconnecting = false;
+        }
+    }
+    async function checkConnectionHealth() {
+        if (!wsClient || reconnecting)
+            return;
+        const state = getWsConnectionState();
+        if (!state)
+            return;
+        if (state.connected) {
+            disconnectedChecks = 0;
+            if (!lastWsStateConnected) {
+                logger.info('Feishu WebSocket is back online');
+                await runBackfill('recovered');
+                disconnectedSince = null;
+            }
+            lastWsStateConnected = true;
+            return;
+        }
+        if (lastWsStateConnected) {
+            disconnectedSince = Date.now();
+            logger.warn({ isConnecting: state.isConnecting }, 'Feishu WebSocket appears offline');
+        }
+        lastWsStateConnected = false;
+        const now = Date.now();
+        const reconnectWindowReady = state.nextConnectTime <= 0 || state.nextConnectTime <= now;
+        if (!reconnectWindowReady)
+            return;
+        disconnectedChecks++;
+        if (disconnectedChecks >= WS_RECONNECT_CHECK_THRESHOLD &&
+            now - reconnectRequestedAt >= WS_RECONNECT_MIN_INTERVAL_MS) {
+            await reconnectWebSocket('health-check');
+        }
+    }
+    function extractCardActionValue(data) {
+        const candidates = [
+            data?.action?.option?.value,
+            data?.action?.value?.selected_value,
+            data?.action?.value?.selectedValue,
+            data?.action?.value?.value,
+            data?.action?.form_value?.value,
+            data?.action?.formValue?.value,
+        ];
+        for (const candidate of candidates) {
+            if (typeof candidate === 'string' && candidate.trim()) {
+                return candidate.trim();
+            }
+        }
+        return null;
+    }
+    async function sendCardActionReply(chatJid, text) {
+        if (!chatJid || !text.trim())
+            return;
+        const chatId = chatJid.startsWith('feishu:') ? chatJid.slice(7) : null;
+        if (!chatId || !client)
+            return;
+        try {
+            await connection.sendMessage(chatId, text.trim());
+        }
+        catch (err) {
+            logger.debug({ err, chatJid }, 'Failed to send Feishu card action reply');
+        }
+    }
+    const connection = {
+        async connect(opts) {
+            const { onReady } = opts;
+            if (!config.appId || !config.appSecret) {
+                logger.warn('Feishu config is empty, running in Web-only mode');
+                return false;
+            }
+            connectOptions = opts;
+            disconnectedChecks = 0;
+            disconnectedSince = null;
+            reconnectRequestedAt = Date.now();
+            reconnecting = false;
+            backfillRunning = false;
+            // Initialize client
+            client = new lark.Client({
+                appId: config.appId,
+                appSecret: config.appSecret,
+                appType: lark.AppType.SelfBuild,
+            });
+            // Fetch bot open_id for mention detection (best-effort, non-blocking)
+            try {
+                const botInfoRes = await client.request({
+                    method: 'GET',
+                    url: '/open-apis/bot/v3/info/',
+                });
+                const info = botInfoRes;
+                botOpenId = info?.bot?.open_id || info?.data?.bot?.open_id || '';
+                if (botOpenId) {
+                    logger.info({ botOpenId }, 'Fetched bot open_id for mention detection');
+                }
+                else {
+                    logger.warn('Could not fetch bot open_id, mention gating will be bypassed');
+                }
+            }
+            catch (err) {
+                logger.warn({ err }, 'Failed to fetch bot info, mention gating will be bypassed');
+                botOpenId = '';
+            }
+            // Create event dispatcher
+            eventDispatcher = new lark.EventDispatcher({}).register({
+                'im.message.receive_v1': async (data) => {
+                    try {
+                        const message = data.message;
+                        await handleIncomingMessage({
+                            chatId: message.chat_id,
+                            messageId: message.message_id,
+                            createTimeMs: toEpochMs(message.create_time),
+                            messageType: message.message_type,
+                            content: message.content,
+                            chatType: message.chat_type,
+                            mentions: message.mentions,
+                            senderOpenId: data.sender.sender_id?.open_id || '',
+                        }, 'ws');
+                    }
+                    catch (err) {
+                        logger.error({ err }, 'Error handling Feishu message');
+                    }
+                },
+                'im.chat.member.bot.added_v1': async (data) => {
+                    try {
+                        const chatId = data.chat_id;
+                        if (!chatId)
+                            return;
+                        const chatJid = `feishu:${chatId}`;
+                        const chatName = data.name || '飞书群聊';
+                        logger.info({ chatJid, chatName }, 'Bot added to Feishu group');
+                        connectOptions?.onBotAddedToGroup?.(chatJid, chatName);
+                    }
+                    catch (err) {
+                        logger.error({ err }, 'Error handling bot added to group event');
+                    }
+                },
+                'im.chat.member.bot.deleted_v1': async (data) => {
+                    try {
+                        const chatId = data.chat_id;
+                        if (!chatId)
+                            return;
+                        const chatJid = `feishu:${chatId}`;
+                        logger.info({ chatJid }, 'Bot removed from Feishu group');
+                        connectOptions?.onBotRemovedFromGroup?.(chatJid);
+                    }
+                    catch (err) {
+                        logger.error({ err }, 'Error handling bot removed from group event');
+                    }
+                },
+                'im.chat.disbanded_v1': async (data) => {
+                    try {
+                        const chatId = data.chat_id;
+                        if (!chatId)
+                            return;
+                        const chatJid = `feishu:${chatId}`;
+                        logger.info({ chatJid }, 'Feishu group disbanded');
+                        connectOptions?.onBotRemovedFromGroup?.(chatJid);
+                    }
+                    catch (err) {
+                        logger.error({ err }, 'Error handling group disbanded event');
+                    }
+                },
+                'card.action.trigger': async (data) => {
+                    try {
+                        const action = data?.action?.value?.action;
+                        const messageId = data?.context?.open_message_id;
+                        const mappedChatJid = messageId
+                            ? resolveJidByMessageId(messageId)
+                            : undefined;
+                        if (action === 'interrupt_stream') {
+                            if (!messageId || !mappedChatJid) {
+                                logger.debug({ messageId }, 'Card action: interrupt ignored because mapping is missing');
+                                return;
+                            }
+                            const session = getStreamingSession(mappedChatJid);
+                            if (!session?.isActive()) {
+                                logger.debug({ chatJid: mappedChatJid, messageId }, 'Card action: session not active');
+                                return;
+                            }
+                            logger.info({ chatJid: mappedChatJid, messageId }, 'Card action: interrupt via button');
+                            connectOptions?.onCardInterrupt?.(mappedChatJid);
+                            return;
+                        }
+                        if (action === 'set_runtime_model' ||
+                            action === 'set_runtime_effort') {
+                            const chatJid = mappedChatJid ||
+                                (typeof data?.context?.open_chat_id === 'string'
+                                    ? `feishu:${data.context.open_chat_id}`
+                                    : null);
+                            if (!chatJid) {
+                                logger.debug({ action, messageId }, 'Card action: runtime update ignored because chat mapping is missing');
+                                return;
+                            }
+                            const selectedValue = extractCardActionValue(data);
+                            if (!selectedValue) {
+                                await sendCardActionReply(chatJid, '运行时切换失败：没有读取到要应用的预设值');
+                                return;
+                            }
+                            logger.info({ chatJid, action, selectedValue, messageId }, 'Card action: updating workspace runtime');
+                            const reply = await connectOptions?.onCardRuntimeUpdate?.(chatJid, {
+                                action,
+                                value: selectedValue,
+                            });
+                            if (reply) {
+                                await sendCardActionReply(chatJid, reply);
+                            }
+                        }
+                    }
+                    catch (err) {
+                        logger.error({ err }, 'Error handling card action trigger');
+                    }
+                },
+            });
+            // Initialize WebSocket client
+            wsClient = new lark.WSClient({
+                appId: config.appId,
+                appSecret: config.appSecret,
+                loggerLevel: lark.LoggerLevel.info,
+            });
+            try {
+                await wsClient.start({ eventDispatcher });
+                logger.info('Feishu WebSocket client started');
+                lastWsStateConnected = true;
+                disconnectedSince = null;
+                startHealthMonitor();
+                onReady();
+                return true;
+            }
+            catch (err) {
+                logger.error({ err }, 'Failed to start Feishu client, running in Web-only mode');
+                // Clean up partially initialized state
+                stopHealthMonitor();
+                connectOptions = null;
+                eventDispatcher = null;
+                client = null;
+                wsClient = null;
+                return false;
+            }
+        },
+        async stop() {
+            stopHealthMonitor();
+            connectOptions = null;
+            eventDispatcher = null;
+            reconnecting = false;
+            disconnectedSince = null;
+            disconnectedChecks = 0;
+            if (wsClient) {
+                logger.info('Stopping Feishu client');
+                try {
+                    await wsClient.close();
+                    logger.info('Feishu client stopped successfully');
+                }
+                catch (err) {
+                    logger.warn({ err }, 'Error stopping Feishu client');
+                }
+                wsClient = null;
+            }
+            client = null;
+            lastWsStateConnected = false;
+        },
+        async sendMessage(chatId, text, localImagePaths) {
+            if (!client) {
+                logger.warn({ chatId }, 'Feishu client not initialized, skip sending message');
+                return;
+            }
+            const clearAckReaction = () => {
+                const ackStored = ackReactionByChat.get(chatId);
+                if (ackStored) {
+                    const [ackMsgId, ackReactionId] = ackStored.split(':');
+                    removeReaction(ackMsgId, ackReactionId).catch(() => { });
+                    ackReactionByChat.delete(chatId);
+                }
+            };
+            try {
+                // Detect pre-built Feishu interactive card JSON — send directly without wrapping
+                if (text.startsWith('{"type":"interactive"')) {
+                    try {
+                        const parsed = JSON.parse(text);
+                        if (parsed.type === 'interactive' && parsed.card) {
+                            const lastMsgId = lastMessageIdByChat.get(chatId);
+                            if (lastMsgId) {
+                                await client.im.message.reply({
+                                    path: { message_id: lastMsgId },
+                                    data: { content: text, msg_type: 'interactive' },
+                                });
+                            }
+                            else {
+                                await client.im.v1.message.create({
+                                    params: { receive_id_type: 'chat_id' },
+                                    data: {
+                                        receive_id: chatId,
+                                        msg_type: 'interactive',
+                                        content: text,
+                                    },
+                                });
+                            }
+                            clearAckReaction();
+                            return;
+                        }
+                    }
+                    catch {
+                        // Not valid card JSON, fall through to normal handling
+                    }
+                }
+                // Count markdown tables to decide format upfront — Feishu cards have a table limit
+                // Each table has exactly one separator row (e.g. |---|---|), so counting those = table count
+                const tableCount = (text.match(/^\|[\s:-]+\|/gm) || []).length;
+                const usePostMd = tableCount > CARD_TABLE_LIMIT;
+                if (usePostMd) {
+                    // Too many tables for card format, go directly to post+md
+                    const postContent = buildPostMdFallback(text);
+                    const lastMsgId = lastMessageIdByChat.get(chatId);
+                    if (lastMsgId) {
+                        await client.im.message.reply({
+                            path: { message_id: lastMsgId },
+                            data: { content: postContent, msg_type: 'post' },
+                        });
+                    }
+                    else {
+                        await client.im.v1.message.create({
+                            params: { receive_id_type: 'chat_id' },
+                            data: {
+                                receive_id: chatId,
+                                msg_type: 'post',
+                                content: postContent,
+                            },
+                        });
+                    }
+                }
+                else {
+                    const card = buildInteractiveCard(text);
+                    const content = JSON.stringify(card);
+                    const lastMsgId = lastMessageIdByChat.get(chatId);
+                    if (lastMsgId) {
+                        try {
+                            await client.im.message.reply({
+                                path: { message_id: lastMsgId },
+                                data: { content, msg_type: 'interactive' },
+                            });
+                        }
+                        catch (err) {
+                            logger.warn({ err, chatId }, 'Feishu interactive reply failed, fallback to post+md');
+                            await client.im.message.reply({
+                                path: { message_id: lastMsgId },
+                                data: {
+                                    content: buildPostMdFallback(text),
+                                    msg_type: 'post',
+                                },
+                            });
+                        }
+                    }
+                    else {
+                        try {
+                            await client.im.v1.message.create({
+                                params: { receive_id_type: 'chat_id' },
+                                data: {
+                                    receive_id: chatId,
+                                    msg_type: 'interactive',
+                                    content,
+                                },
+                            });
+                        }
+                        catch (err) {
+                            logger.warn({ err, chatId }, 'Feishu interactive create failed, fallback to post+md');
+                            await client.im.v1.message.create({
+                                params: { receive_id_type: 'chat_id' },
+                                data: {
+                                    receive_id: chatId,
+                                    msg_type: 'post',
+                                    content: buildPostMdFallback(text),
+                                },
+                            });
+                        }
+                    }
+                }
+                logger.debug({ chatId }, 'Sent Feishu card message');
+                clearAckReaction();
+                for (const localImagePath of localImagePaths || []) {
+                    try {
+                        const uploadRes = (await client.im.v1.image.create({
+                            data: {
+                                image_type: 'message',
+                                image: fs.createReadStream(localImagePath),
+                            },
+                        }));
+                        const imageKey = uploadRes?.image_key ?? uploadRes?.data?.image_key;
+                        if (!imageKey) {
+                            logger.warn({ chatId, localImagePath }, 'Feishu image upload returned no image_key');
+                            continue;
+                        }
+                        await client.im.v1.message.create({
+                            params: { receive_id_type: 'chat_id' },
+                            data: {
+                                receive_id: chatId,
+                                msg_type: 'image',
+                                content: JSON.stringify({ image_key: imageKey }),
+                            },
+                        });
+                    }
+                    catch (imageErr) {
+                        logger.warn({ chatId, localImagePath, err: imageErr }, 'Failed to send Feishu image attachment');
+                    }
+                }
+            }
+            catch (err) {
+                logger.error({ err, chatId }, 'Failed to send Feishu card message');
+                clearAckReaction();
+            }
+        },
+        async sendImage(chatId, imageBuffer, mimeType, caption, _fileName /* Feishu image API has no filename field, intentionally unused */) {
+            if (!client) {
+                logger.warn({ chatId }, 'Feishu client not initialized, skip sending image');
+                return;
+            }
+            try {
+                // Step 1: Upload image to Feishu to get image_key
+                const uploadResult = (await client.im.v1.image.create({
+                    data: {
+                        image_type: 'message',
+                        image: imageBuffer,
+                    },
+                }));
+                const imageKey = uploadResult?.image_key ?? uploadResult?.data?.image_key;
+                if (!imageKey) {
+                    logger.error({ chatId }, 'Feishu image upload failed: no image_key returned');
+                    throw new Error('Feishu image upload failed: no image_key in response');
+                }
+                // Step 2: Send image message
+                // receive_id_type: group chat ids start with "oc_", DM open_ids start with "ou_"
+                const receive_id_type = chatId.startsWith('oc_')
+                    ? 'chat_id'
+                    : 'open_id';
+                const lastMsgId = lastMessageIdByChat.get(chatId);
+                const content = JSON.stringify({ image_key: imageKey });
+                if (lastMsgId) {
+                    await client.im.message.reply({
+                        path: { message_id: lastMsgId },
+                        data: { content, msg_type: 'image' },
+                    });
+                }
+                else {
+                    await client.im.v1.message.create({
+                        params: { receive_id_type },
+                        data: {
+                            receive_id: chatId,
+                            msg_type: 'image',
+                            content,
+                        },
+                    });
+                }
+                // Step 3: If caption provided, send it as a follow-up text message
+                if (caption) {
+                    await client.im.v1.message.create({
+                        params: { receive_id_type },
+                        data: {
+                            receive_id: chatId,
+                            msg_type: 'text',
+                            content: JSON.stringify({ text: caption }),
+                        },
+                    });
+                }
+                logger.info({ chatId, imageKey, mimeType, size: imageBuffer.length }, 'Feishu image sent');
+            }
+            catch (err) {
+                logger.error({ err, chatId, mimeType }, 'Failed to send Feishu image');
+                throw err;
+            }
+        },
+        async sendFile(chatId, filePath, fileName) {
+            if (!client) {
+                logger.warn({ chatId }, 'Feishu client not initialized, skip sending file');
+                return;
+            }
+            try {
+                const buffer = await fsPromises.readFile(filePath);
+                // Check file size limit (30MB)
+                const MAX_FILE_SIZE = 30 * 1024 * 1024;
+                if (buffer.length > MAX_FILE_SIZE) {
+                    throw new Error(`文件大小超过 30MB 限制 (${(buffer.length / 1024 / 1024).toFixed(2)}MB)`);
+                }
+                const ext = path.extname(fileName);
+                const fileType = getFileType(ext);
+                // Upload file
+                const uploadResult = (await client.im.v1.file.create({
+                    data: {
+                        file_type: fileType,
+                        file_name: fileName,
+                        file: buffer,
+                    },
+                }));
+                const fileKey = uploadResult?.file_key ?? uploadResult?.data?.file_key;
+                if (!fileKey) {
+                    throw new Error('文件上传失败：未返回 file_key');
+                }
+                // Send file message
+                const receive_id_type = chatId.startsWith('oc_')
+                    ? 'chat_id'
+                    : 'open_id';
+                await client.im.v1.message.create({
+                    params: { receive_id_type },
+                    data: {
+                        receive_id: chatId,
+                        msg_type: 'file',
+                        content: JSON.stringify({ file_key: fileKey }),
+                    },
+                });
+                logger.info({ chatId, fileName, fileSize: buffer.length }, 'File sent to Feishu');
+            }
+            catch (err) {
+                logger.error({ err, chatId, filePath }, 'Failed to send file to Feishu');
+                throw err;
+            }
+        },
+        async sendReaction(chatId, isTyping) {
+            if (!client)
+                return;
+            const lastMsgId = lastMessageIdByChat.get(chatId);
+            if (!lastMsgId)
+                return;
+            if (isTyping) {
+                const reactionId = await addReaction(lastMsgId, 'OnIt');
+                if (reactionId) {
+                    typingReactionByChat.set(chatId, `${lastMsgId}:${reactionId}`);
+                }
+            }
+            else {
+                const stored = typingReactionByChat.get(chatId);
+                if (stored) {
+                    const [msgId, reactionId] = stored.split(':');
+                    await removeReaction(msgId, reactionId);
+                    typingReactionByChat.delete(chatId);
+                }
+            }
+        },
+        clearAckReaction(chatId) {
+            const ackStored = ackReactionByChat.get(chatId);
+            if (ackStored) {
+                const [ackMsgId, ackReactionId] = ackStored.split(':');
+                removeReaction(ackMsgId, ackReactionId).catch(() => { });
+                ackReactionByChat.delete(chatId);
+            }
+        },
+        isConnected() {
+            return wsClient != null;
+        },
+        async getChatInfo(chatId) {
+            if (!client)
+                return null;
+            try {
+                const res = await client.im.v1.chat.get({
+                    path: { chat_id: chatId },
+                });
+                if (!res.data)
+                    return null;
+                return {
+                    avatar: res.data.avatar,
+                    name: res.data.name,
+                    user_count: res.data.user_count,
+                    chat_type: res.data.chat_type,
+                    chat_mode: res.data.chat_mode,
+                };
+            }
+            catch (err) {
+                logger.warn({ err, chatId }, 'Failed to get Feishu chat info');
+                return null;
+            }
+        },
+        async syncGroups() {
+            if (!client) {
+                logger.debug('Feishu client not initialized, skip group sync');
+                return;
+            }
+            try {
+                let pageToken;
+                let hasMore = true;
+                while (hasMore) {
+                    const res = await client.im.v1.chat.list({
+                        params: {
+                            page_size: 100,
+                            page_token: pageToken,
+                        },
+                    });
+                    const items = res.data?.items || [];
+                    for (const chat of items) {
+                        if (chat.chat_id && chat.name) {
+                            updateChatName(`feishu:${chat.chat_id}`, chat.name);
+                            knownChatIds.add(chat.chat_id);
+                        }
+                    }
+                    hasMore = res.data?.has_more || false;
+                    pageToken = res.data?.page_token;
+                }
+                setLastGroupSync();
+                logger.info('Feishu group sync completed');
+            }
+            catch (err) {
+                logger.error({ err }, 'Failed to sync Feishu groups');
+            }
+        },
+        getLarkClient() {
+            return client;
+        },
+        getLastMessageId(chatId) {
+            return lastMessageIdByChat.get(chatId);
+        },
+    };
+    return connection;
+}
+// ─── Backward-compatible global singleton ──────────────────────
+// @deprecated — 旧的顶层导出函数，内部使用一个默认全局实例。
+// 后续由 imManager 替代。
+let _defaultInstance = null;
+/**
+ * @deprecated Use createFeishuConnection() factory instead. Will be replaced by imManager.
+ * Connect to Feishu via WebSocket and start receiving messages.
+ */
+export async function connectFeishu(opts) {
+    const { getFeishuProviderConfigWithSource } = await import('./runtime-config.js');
+    const { config, source } = getFeishuProviderConfigWithSource();
+    if (!config.appId || !config.appSecret) {
+        logger.warn({ source }, 'Feishu config is empty, running in Web-only mode (set it in Settings -> Feishu config)');
+        return false;
+    }
+    _defaultInstance = createFeishuConnection({
+        appId: config.appId,
+        appSecret: config.appSecret,
+    });
+    return _defaultInstance.connect(opts);
+}
+/**
+ * @deprecated Use FeishuConnection.sendMessage() instead.
+ */
+export async function sendFeishuMessage(chatId, text, localImagePaths) {
+    if (!_defaultInstance) {
+        logger.warn({ chatId }, 'Feishu client not initialized, skip sending message');
+        return;
+    }
+    return _defaultInstance.sendMessage(chatId, text, localImagePaths);
+}
+/**
+ * @deprecated Use FeishuConnection.sendReaction() instead.
+ */
+export async function setFeishuTyping(chatId, isTyping) {
+    if (!_defaultInstance)
+        return;
+    return _defaultInstance.sendReaction(chatId, isTyping);
+}
+/**
+ * @deprecated Use FeishuConnection.syncGroups() instead.
+ */
+export async function syncFeishuGroups() {
+    if (!_defaultInstance) {
+        logger.debug('Feishu client not initialized, skip group sync');
+        return;
+    }
+    return _defaultInstance.syncGroups();
+}
+/**
+ * @deprecated Use FeishuConnection.isConnected() instead.
+ */
+export function isFeishuConnected() {
+    return _defaultInstance?.isConnected() ?? false;
+}
+/**
+ * @deprecated Use FeishuConnection.stop() instead.
+ */
+export async function stopFeishu() {
+    if (_defaultInstance) {
+        await _defaultInstance.stop();
+        _defaultInstance = null;
+    }
+}