pikiloop 0.4.0

package/dist/channels/feishu/channel.js

@@ -0,0 +1,911 @@
+/**
+ * Feishu channel — Feishu/Lark Open Platform transport using official SDK.
+ *
+ * Uses @larksuiteoapi/node-sdk for:
+ *   - WSClient + EventDispatcher: WebSocket event receiving with auto-reconnect
+ *   - Client.im: message send/edit/delete, image/file upload, resource download
+ *   - Automatic tenant_access_token management
+ *
+ * All messages are sent as regular interactive cards (no CardKit streaming).
+ */
+import * as lark from '@larksuiteoapi/node-sdk';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Channel, DEFAULT_CHANNEL_CAPABILITIES, sleep, } from '../base.js';
+import { FEISHU_LIMITS } from '../../core/constants.js';
+import { ChannelHealth } from '../health.js';
+import { adaptMarkdownForFeishu } from './markdown.js';
+import { writeScopedLog, shouldLog } from '../../core/logging.js';
+import { recordKnownChatId } from '../../core/config/user-config.js';
+export { FeishuChannel };
+const FEISHU_CARD_MAX = FEISHU_LIMITS.cardMax;
+const FILE_MAX_BYTES = FEISHU_LIMITS.fileMaxBytes;
+const PHOTO_EXTS = new Set(['.jpg', '.jpeg', '.png', '.webp', '.gif']);
+const FEISHU_WS_START_RETRY_MAX_DELAY_MS = FEISHU_LIMITS.wsStartRetryMaxDelay;
+function describeError(err) {
+    if (!(err instanceof Error))
+        return String(err ?? 'unknown error');
+    const parts = [`${err.name}: ${err.message}`];
+    for (const key of ['code', 'errno', 'syscall', 'address', 'port', 'host', 'hostname']) {
+        const value = err?.[key];
+        if (value != null && value !== '')
+            parts.push(`${key}=${value}`);
+    }
+    return parts.join(' | ');
+}
+function isRetryableWsStartError(err) {
+    const text = describeError(err).toLowerCase();
+    return [
+        'socket hang up',
+        'econnreset',
+        'etimedout',
+        'econnrefused',
+        'enotfound',
+        'eai_again',
+        'fetch failed',
+        'timeout',
+        'bad gateway',
+        'service unavailable',
+        'gateway timeout',
+    ].some(token => text.includes(token));
+}
+function isRetryableUploadError(err) {
+    const text = describeError(err).toLowerCase();
+    return [
+        'socket hang up',
+        'econnreset',
+        'etimedout',
+        'econnrefused',
+        'enotfound',
+        'eai_again',
+        'fetch failed',
+        'timeout',
+        'temporarily unavailable',
+        'internal server error',
+        'bad gateway',
+        'service unavailable',
+        'gateway timeout',
+    ].some(token => text.includes(token));
+}
+function requireMessageId(resp, action) {
+    const messageId = resp?.data?.message_id;
+    if (messageId)
+        return String(messageId);
+    const code = resp?.code;
+    const msg = resp?.msg || resp?.message || 'no message_id returned';
+    throw new Error(`${action} failed: code=${code ?? '?'} msg=${msg}`);
+}
+/** Treat "card content didn't change" responses as a successful no-op edit. */
+function isFeishuNotModifiedMessage(msg) {
+    if (!msg)
+        return false;
+    const lower = msg.toLowerCase();
+    return lower.includes('not modified')
+        || lower.includes('not modify')
+        || lower.includes('content not change')
+        || lower.includes('same content')
+        || lower.includes('same as before')
+        || lower.includes('no change');
+}
+function buildPostContent(paragraphs, title = '') {
+    return JSON.stringify({
+        zh_cn: {
+            title,
+            content: paragraphs,
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Card builder helper
+// ---------------------------------------------------------------------------
+function inferActionLayout(actions) {
+    if (actions.length >= 3)
+        return 'trisection';
+    if (actions.length === 2)
+        return 'bisected';
+    return undefined;
+}
+function chunkActionRows(actions, size = 3) {
+    const rows = [];
+    for (let i = 0; i < actions.length; i += size) {
+        const rowActions = actions.slice(i, i + size).filter(Boolean);
+        if (!rowActions.length)
+            continue;
+        rows.push({ actions: rowActions, layout: inferActionLayout(rowActions) });
+    }
+    return rows;
+}
+function keyboardToRows(keyboard) {
+    const explicitRows = Array.isArray(keyboard?.rows)
+        ? keyboard.rows
+            .filter((row) => Array.isArray(row?.actions) && row.actions.length)
+            .map((row) => ({
+            actions: row.actions.filter(Boolean),
+            layout: row.layout || inferActionLayout(row.actions),
+        }))
+        : [];
+    if (explicitRows.length)
+        return explicitRows;
+    const actions = Array.isArray(keyboard?.actions)
+        ? keyboard.actions.filter(Boolean)
+        : [];
+    return chunkActionRows(actions);
+}
+function buildCardFromView(view) {
+    const adapted = adaptMarkdownForFeishu(view.markdown);
+    const content = adapted.length > FEISHU_CARD_MAX
+        ? adapted.slice(0, FEISHU_CARD_MAX) + '\n\n...(truncated)'
+        : adapted;
+    const actionElements = [];
+    for (const row of view.rows || []) {
+        const actions = row.actions.filter(Boolean);
+        if (!actions.length)
+            continue;
+        const element = { tag: 'action', actions };
+        const layout = row.layout || inferActionLayout(actions);
+        if (layout)
+            element.layout = layout;
+        actionElements.push(element);
+    }
+    // Card JSON 2.0 supports tables in markdown but dropped `tag: action`.
+    // Use v2 for content-only cards; fall back to v1 when buttons are needed.
+    if (actionElements.length) {
+        const card = {
+            config: { wide_screen_mode: true, update_multi: true },
+            elements: [{ tag: 'markdown', content }, ...actionElements],
+        };
+        if (view.title) {
+            card.header = {
+                template: view.template || 'blue',
+                title: { content: view.title, tag: 'plain_text' },
+            };
+        }
+        return card;
+    }
+    const card = {
+        schema: '2.0',
+        config: { update_multi: true },
+        body: { elements: [{ tag: 'markdown', content }] },
+    };
+    if (view.title) {
+        card.header = {
+            template: view.template || 'blue',
+            title: { content: view.title, tag: 'plain_text' },
+        };
+    }
+    return card;
+}
+// ---------------------------------------------------------------------------
+// FeishuChannel
+// ---------------------------------------------------------------------------
+class FeishuChannel extends Channel {
+    capabilities = {
+        ...DEFAULT_CHANNEL_CAPABILITIES,
+        editMessages: true,
+        commandMenu: true,
+        messageReactions: true,
+        sendImage: true,
+    };
+    /** Implementation of Channel.sendImage — uploads the buffer as an image
+     *  message. When a caption is supplied, falls back to a post with both an
+     *  img tag and a text line (Feishu's `msg_type:'image'` doesn't have a
+     *  native caption field). */
+    async sendImage(chatId, bytes, opts) {
+        const caption = opts.caption?.trim() || '';
+        const replyTo = opts.replyTo ? String(opts.replyTo) : undefined;
+        const imageKey = await this.uploadImage(bytes);
+        if (caption) {
+            return await this.sendPost(String(chatId), buildPostContent([
+                [{ tag: 'img', image_key: imageKey }],
+                [{ tag: 'text', text: caption }],
+            ]), { replyTo });
+        }
+        const msgContent = JSON.stringify({ image_key: imageKey });
+        this._logOutgoing('sendImage', `${replyTo ? `reply_to=${replyTo}` : `chat=${chatId}`} bytes=${bytes.byteLength}`);
+        const resp = replyTo
+            ? await this.client.im.message.reply({ path: { message_id: replyTo }, data: { msg_type: 'image', content: msgContent } })
+            : await this.client.im.message.create({ params: { receive_id_type: 'chat_id' }, data: { receive_id: String(chatId), msg_type: 'image', content: msgContent } });
+        return requireMessageId(resp, 'send image');
+    }
+    appId;
+    appSecret;
+    domain;
+    workdir;
+    allowedChatIds;
+    client;
+    wsClient = null;
+    eventDispatcher;
+    running = false;
+    messageChains = new Map();
+    /** Recently processed message IDs — guards against Feishu server retries. */
+    _seenMessageIds = new Set();
+    _seenMessageIdQueue = [];
+    static SEEN_MESSAGE_CAP = 256;
+    /** Maps open_id → chat_id for resolving menu event context. */
+    _openIdToChat = new Map();
+    _hCommand = null;
+    _hMessage = null;
+    _hCardAction = null;
+    _hRecall = null;
+    _hError = null;
+    knownChats = new Set();
+    /** Resolves when wsClient.start() settles (used by listen() to block). */
+    _listenResolve = null;
+    constructor(opts) {
+        super();
+        this.appId = opts.appId;
+        this.appSecret = opts.appSecret;
+        this.domain = (opts.domain ?? 'https://open.feishu.cn').replace(/\/+$/, '');
+        this.workdir = opts.workdir ?? process.cwd();
+        this.allowedChatIds = opts.allowedChatIds ?? new Set();
+        // Resolve SDK domain enum or custom string
+        const sdkDomain = this.domain.includes('larksuite.com')
+            ? lark.Domain.Lark
+            : this.domain === 'https://open.feishu.cn'
+                ? lark.Domain.Feishu
+                : this.domain;
+        this.client = new lark.Client({
+            appId: this.appId,
+            appSecret: this.appSecret,
+            domain: sdkDomain,
+            loggerLevel: lark.LoggerLevel.warn,
+        });
+        this.eventDispatcher = new lark.EventDispatcher({});
+        this._registerEvents();
+    }
+    // ---- Hook registration ---------------------------------------------------
+    onCommand(h) { this._hCommand = h; }
+    onMessage(h) { this._hMessage = h; }
+    onCallback(h) { this._hCardAction = h; }
+    onMessageRecalled(h) { this._hRecall = h; }
+    onError(h) { this._hError = h; }
+    // ========================================================================
+    // Lifecycle
+    // ========================================================================
+    async connect() {
+        // Get bot info via raw request (SDK doesn't have a dedicated bot info method)
+        try {
+            const resp = await this.client.request({
+                method: 'GET',
+                url: '/open-apis/bot/v3/info',
+                data: {},
+            });
+            this._debug(`[connect] bot info resp: ${JSON.stringify(resp)}`);
+            const info = resp?.bot;
+            this.bot = {
+                id: info?.open_id || this.appId,
+                username: info?.app_name || 'pikiloop',
+                displayName: info?.app_name || 'pikiloop',
+            };
+        }
+        catch (e) {
+            this._log(`[connect] bot info failed: ${e?.message || e}`, 'warn');
+            this.bot = { id: this.appId, username: 'pikiloop', displayName: 'pikiloop' };
+        }
+        return this.bot;
+    }
+    async listen() {
+        this.running = true;
+        const health = new ChannelHealth({
+            label: 'Feishu',
+            opAction: 'WS start',
+            initialDelayMs: FEISHU_LIMITS.wsStartRetryInitialDelay,
+            maxDelayMs: FEISHU_WS_START_RETRY_MAX_DELAY_MS,
+            sustainedFailureHint: 'verify feishuAppId / feishuAppSecret in setting.json',
+            log: (msg, level) => this._log(msg, level),
+        });
+        while (this.running) {
+            const sdkDomain = this.domain.includes('larksuite.com')
+                ? lark.Domain.Lark
+                : this.domain === 'https://open.feishu.cn'
+                    ? lark.Domain.Feishu
+                    : this.domain;
+            this.wsClient = new lark.WSClient({
+                appId: this.appId,
+                appSecret: this.appSecret,
+                domain: sdkDomain,
+                loggerLevel: lark.LoggerLevel.warn,
+                autoReconnect: true,
+            });
+            this._debug('[ws] starting SDK WSClient...');
+            try {
+                await this.wsClient.start({ eventDispatcher: this.eventDispatcher });
+                this._debug('[ws] WSClient started, listening for events');
+                health.recordSuccess();
+                break;
+            }
+            catch (err) {
+                try {
+                    this.wsClient.close({ force: true });
+                }
+                catch { }
+                this.wsClient = null;
+                if (!this.running)
+                    return;
+                if (!isRetryableWsStartError(err))
+                    throw err;
+                await sleep(health.recordFailure(err));
+            }
+        }
+        if (!this.running || !this.wsClient)
+            return;
+        // Block until disconnect() is called
+        await new Promise(resolve => {
+            this._listenResolve = resolve;
+            if (!this.running)
+                resolve();
+        });
+    }
+    disconnect() {
+        this.running = false;
+        if (this.wsClient) {
+            try {
+                this.wsClient.close({ force: true });
+            }
+            catch { }
+            this.wsClient = null;
+        }
+        this._listenResolve?.();
+        this._listenResolve = null;
+    }
+    // ========================================================================
+    // Event handling (via SDK EventDispatcher)
+    // ========================================================================
+    _registerEvents() {
+        this.eventDispatcher.register({
+            'im.message.receive_v1': (data) => {
+                void this._handleMessageEvent(data).catch(e => {
+                    this._log(`[dispatch] error: ${e}`, 'warn');
+                    this._hError?.(e instanceof Error ? e : new Error(String(e)));
+                });
+            },
+            'card.action.trigger': (data) => {
+                void this._dispatchCardAction(data).catch(e => {
+                    this._log(`[card-action] error: ${e}`, 'warn');
+                    this._hError?.(e instanceof Error ? e : new Error(String(e)));
+                });
+                return {};
+            },
+            'application.bot.menu_v6': (data) => {
+                void this._dispatchMenuEvent(data).catch(e => {
+                    this._log(`[menu] error: ${e}`, 'warn');
+                    this._hError?.(e instanceof Error ? e : new Error(String(e)));
+                });
+            },
+            'im.message.recalled_v1': (data) => {
+                void this._dispatchMessageRecalled(data).catch(e => {
+                    this._log(`[message-recalled] error: ${e}`, 'warn');
+                    this._hError?.(e instanceof Error ? e : new Error(String(e)));
+                });
+            },
+        });
+    }
+    async _handleMessageEvent(event) {
+        if (shouldLog('debug'))
+            this._debug(`[recv] raw event received: ${JSON.stringify(event)}`);
+        const msg = event?.message;
+        if (!msg) {
+            this._debug(`[recv] event has no message object`);
+            return;
+        }
+        const chatId = msg.chat_id;
+        const messageId = msg.message_id;
+        const chatType = msg.chat_type === 'p2p' ? 'p2p' : 'group';
+        const msgType = msg.message_type;
+        if (!chatId || !messageId)
+            return;
+        // Dedup: Feishu server may retry events when the ack is slow
+        if (this._seenMessageIds.has(messageId)) {
+            this._debug(`[recv] dedup: message=${messageId} already processed, skipping`);
+            return;
+        }
+        this._seenMessageIds.add(messageId);
+        this._seenMessageIdQueue.push(messageId);
+        while (this._seenMessageIdQueue.length > FeishuChannel.SEEN_MESSAGE_CAP) {
+            this._seenMessageIds.delete(this._seenMessageIdQueue.shift());
+        }
+        if (!this._isAllowed(chatId)) {
+            this._log(`[recv] blocked: chat=${chatId} not allowed`, 'warn');
+            return;
+        }
+        this._trackChat(chatId);
+        const sender = event.sender;
+        // Skip messages from the bot itself
+        if (sender?.sender_type === 'app')
+            return;
+        const from = {
+            openId: sender?.sender_id?.open_id || '',
+            userId: sender?.sender_id?.user_id,
+            name: '',
+        };
+        // Track open_id → chat_id for menu event resolution
+        if (from.openId)
+            this._openIdToChat.set(from.openId, chatId);
+        // Group: require @mention
+        if (chatType === 'group') {
+            if (shouldLog('debug'))
+                this._debug(`[recv] group check mention: bot=${JSON.stringify(this.bot)}, mentions=${JSON.stringify(msg.mentions)}`);
+            if (!this._isBotMentioned(msg)) {
+                this._debug(`[recv] skipped: not mentioned in group ${chatId}`);
+                return;
+            }
+        }
+        const parentId = typeof msg.parent_id === 'string' && msg.parent_id ? msg.parent_id : null;
+        const ctx = this._makeCtx(chatId, messageId, from, chatType, event, parentId);
+        // Parse message content
+        let text = '';
+        const files = [];
+        try {
+            const content = JSON.parse(msg.content || '{}');
+            if (msgType === 'text') {
+                text = this._cleanMention(content.text || '');
+            }
+            else if (msgType === 'image') {
+                if (content.image_key) {
+                    try {
+                        const localPath = await this._downloadResource(messageId, content.image_key, 'image');
+                        files.push(localPath);
+                    }
+                    catch (e) {
+                        this._log(`[recv] image download failed: ${e}`, 'warn');
+                    }
+                }
+            }
+            else if (msgType === 'file') {
+                if (content.file_key) {
+                    try {
+                        const localPath = await this._downloadResource(messageId, content.file_key, 'file', content.file_name);
+                        files.push(localPath);
+                    }
+                    catch (e) {
+                        this._log(`[recv] file download failed: ${e}`, 'warn');
+                    }
+                }
+            }
+            else if (msgType === 'post') {
+                text = this._cleanMention(this._extractPostText(content));
+            }
+            else {
+                text = this._cleanMention(content.text || '');
+            }
+        }
+        catch (e) {
+            this._log(`[recv] content parse error: ${e.message || e}`, 'warn');
+            return;
+        }
+        const trimmedText = text.trim();
+        // Queue dispatch per chat to preserve ordering
+        const key = chatId;
+        const prev = this.messageChains.get(key) || Promise.resolve();
+        const current = prev.catch(() => { }).then(async () => {
+            // Command dispatch
+            if (trimmedText.startsWith('/') && this._hCommand) {
+                const spaceIdx = trimmedText.indexOf(' ');
+                const cmd = (spaceIdx > 0 ? trimmedText.slice(1, spaceIdx) : trimmedText.slice(1)).toLowerCase();
+                const args = spaceIdx > 0 ? trimmedText.slice(spaceIdx + 1).trim() : '';
+                await this._hCommand(cmd, args, ctx);
+                return;
+            }
+            // Message dispatch
+            if (!this._hMessage)
+                return;
+            if (!trimmedText && !files.length)
+                return;
+            await this._hMessage({ text: trimmedText, files }, ctx);
+        });
+        const settled = current.catch(e => {
+            this._log(`[dispatch] handler error: ${e}`, 'warn');
+            this._hError?.(e instanceof Error ? e : new Error(String(e)));
+        }).finally(() => {
+            if (this.messageChains.get(key) === settled)
+                this.messageChains.delete(key);
+        });
+        this.messageChains.set(key, settled);
+        await settled;
+    }
+    async _dispatchCardAction(event) {
+        const chatId = event.context?.open_chat_id;
+        const messageId = event.context?.open_message_id;
+        const actionStr = event.action?.value?.action;
+        if (!chatId || !actionStr || !this._hCardAction)
+            return;
+        if (!this._isAllowed(chatId)) {
+            this._debug(`[card-action] blocked: chat=${chatId}`);
+            return;
+        }
+        const from = {
+            openId: event.operator?.open_id || '',
+            userId: event.operator?.user_id,
+        };
+        this._debug(`[recv] card_action chat=${chatId} msg=${messageId} action="${actionStr}"`);
+        await this._hCardAction(actionStr, {
+            chatId,
+            messageId,
+            from,
+            editReply: (msgId, text, opts) => this.editMessage(chatId, msgId, text, opts),
+            channel: this,
+            raw: event,
+        });
+    }
+    async _dispatchMenuEvent(event) {
+        const eventKey = event.event_key;
+        const openId = event.operator?.operator_id?.open_id;
+        if (!eventKey || !openId || !this._hCommand)
+            return;
+        // Try: event payload → cache → API resolve
+        const chatId = this._openIdToChat.get(openId)
+            ?? await this._resolveP2pChatId(openId);
+        if (!chatId) {
+            this._log(`[menu] cannot resolve chat_id for open_id=${openId}, event_key=${eventKey}`, 'warn');
+            return;
+        }
+        if (!this._isAllowed(chatId))
+            return;
+        this._debug(`[recv] menu event_key=${eventKey} open_id=${openId} chat=${chatId}`);
+        const from = { openId, userId: event.operator?.operator_id?.user_id };
+        const ctx = this._makeCtx(chatId, '', from, 'p2p', event);
+        await this._hCommand(eventKey, '', ctx);
+    }
+    async _dispatchMessageRecalled(event) {
+        const chatId = String(event?.chat_id || '').trim();
+        const messageId = String(event?.message_id || '').trim();
+        if (!chatId || !messageId || !this._hRecall)
+            return;
+        if (!this._isAllowed(chatId)) {
+            this._debug(`[message-recalled] blocked: chat=${chatId}`);
+            return;
+        }
+        this._trackChat(chatId);
+        this._debug(`[recv] message_recalled chat=${chatId} msg=${messageId}`);
+        await this._hRecall(messageId, chatId, event);
+    }
+    /**
+     * Resolve a p2p chat_id for a given open_id by sending a minimal message
+     * via open_id and extracting the chat_id from the API response.
+     */
+    async _resolveP2pChatId(openId) {
+        try {
+            const resp = await this.client.im.message.create({
+                params: { receive_id_type: 'open_id' },
+                data: {
+                    receive_id: openId,
+                    msg_type: 'text',
+                    content: JSON.stringify({ text: '...' }),
+                },
+            });
+            const chatId = resp?.data?.chat_id ?? null;
+            const msgId = resp?.data?.message_id;
+            // Clean up the placeholder message
+            if (msgId) {
+                try {
+                    await this.client.im.message.delete({ path: { message_id: msgId } });
+                }
+                catch { }
+            }
+            if (chatId) {
+                this._openIdToChat.set(openId, chatId);
+                this._trackChat(chatId);
+                this._debug(`[menu] resolved chat_id=${chatId} for open_id=${openId}`);
+            }
+            return chatId;
+        }
+        catch (e) {
+            this._log(`[menu] resolve chat_id failed for open_id=${openId}: ${e?.message || e}`, 'warn');
+            return null;
+        }
+    }
+    // ========================================================================
+    // Outgoing primitives (Channel interface)
+    // ========================================================================
+    async setMenu(commands) {
+        this._debug(`[menu] ${commands.length} commands. Configure in Feishu Developer Console → Bot → Custom Menu:`);
+        for (const c of commands) {
+            this._debug(`[menu]   event_key="${c.command}"  name="${c.description}"`);
+        }
+    }
+    async clearMenu() {
+        this._debug('[menu] cleared (remove items in Feishu Developer Console)');
+    }
+    async sendCard(chatId, view) {
+        const card = buildCardFromView(view);
+        this._logOutgoing('send', `chat=${chatId} chars=${view.markdown.length} rows=${view.rows?.length || 0}`);
+        const resp = await this.client.im.message.create({
+            params: { receive_id_type: 'chat_id' },
+            data: {
+                receive_id: String(chatId),
+                msg_type: 'interactive',
+                content: JSON.stringify(card),
+            },
+        });
+        return requireMessageId(resp, 'send interactive card');
+    }
+    async send(chatId, text, opts = {}) {
+        const rows = keyboardToRows(opts.keyboard);
+        const view = { markdown: text.trim() || '(empty)', rows };
+        // Reply to a specific message if replyTo is set
+        if (opts.replyTo) {
+            return await this.replyCard(String(opts.replyTo), view);
+        }
+        return await this.sendCard(chatId, view);
+    }
+    async replyCard(replyToMsgId, view) {
+        const card = buildCardFromView(view);
+        this._logOutgoing('reply', `reply_to=${replyToMsgId} chars=${view.markdown.length} rows=${view.rows?.length || 0}`);
+        const resp = await this.client.im.message.reply({
+            path: { message_id: replyToMsgId },
+            data: {
+                msg_type: 'interactive',
+                content: JSON.stringify(card),
+            },
+        });
+        return requireMessageId(resp, 'reply interactive card');
+    }
+    async editCard(chatId, msgId, view) {
+        if (!view.markdown.trim())
+            return;
+        const card = buildCardFromView(view);
+        this._logOutgoing('edit', `chat=${chatId} msg_id=${msgId} chars=${view.markdown.length} rows=${view.rows?.length || 0}`);
+        // The Lark SDK's response interceptor returns the JSON body for any HTTP 2xx, so
+        // Feishu application errors (`code != 0`) never throw — they look like success here.
+        // Inspect the response code ourselves so callers can fall back to a fresh send.
+        let resp;
+        try {
+            resp = await this.client.im.message.patch({
+                path: { message_id: String(msgId) },
+                data: { content: JSON.stringify(card) },
+            });
+        }
+        catch (e) {
+            const msg = String(e?.message || e).toLowerCase();
+            if (isFeishuNotModifiedMessage(msg))
+                return;
+            const err = e instanceof Error ? e : new Error(String(e ?? 'edit card failed'));
+            err.feishuEditFailed = true;
+            throw err;
+        }
+        const code = resp?.code;
+        if (code != null && code !== 0) {
+            const msg = String(resp?.msg ?? resp?.message ?? '').trim();
+            if (isFeishuNotModifiedMessage(msg))
+                return;
+            const err = new Error(`edit card failed: code=${code} msg=${msg || '(no message)'}`);
+            err.feishuCode = code;
+            err.feishuEditFailed = true;
+            throw err;
+        }
+    }
+    async editMessage(chatId, msgId, text, opts = {}) {
+        if (!text.trim())
+            return;
+        const rows = keyboardToRows(opts.keyboard);
+        await this.editCard(chatId, msgId, {
+            markdown: text,
+            rows,
+        });
+    }
+    async deleteMessage(_chatId, msgId) {
+        try {
+            await this.client.im.message.delete({
+                path: { message_id: String(msgId) },
+            });
+        }
+        catch { }
+    }
+    async sendTyping(_chatId) {
+        // Feishu has no typing indicator API — no-op
+    }
+    async setMessageReaction(_chatId, msgId, reactions) {
+        const messageId = String(msgId || '').trim();
+        const emojiTypes = [...new Set(reactions.map(reaction => String(reaction || '').trim()).filter(Boolean))];
+        if (!messageId || !emojiTypes.length)
+            return;
+        this._logOutgoing('setReaction', `msg_id=${messageId} reactions=${emojiTypes.join(',')}`);
+        for (const emojiType of emojiTypes) {
+            await this.client.im.messageReaction.create({
+                path: { message_id: messageId },
+                data: { reaction_type: { emoji_type: emojiType } },
+            }).catch(() => { });
+        }
+    }
+    // ========================================================================
+    // Feishu-specific outgoing
+    // ========================================================================
+    /** Send a text message (not card). For simple notifications. */
+    async sendText(chatId, text) {
+        const resp = await this.client.im.message.create({
+            params: { receive_id_type: 'chat_id' },
+            data: {
+                receive_id: chatId,
+                msg_type: 'text',
+                content: JSON.stringify({ text }),
+            },
+        });
+        return requireMessageId(resp, 'send text');
+    }
+    async sendPost(chatId, content, opts = {}) {
+        const replyTo = opts.replyTo ? String(opts.replyTo) : undefined;
+        this._logOutgoing('sendPost', `${replyTo ? `reply_to=${replyTo}` : `chat=${chatId}`} chars=${content.length}`);
+        const resp = replyTo
+            ? await this.client.im.message.reply({
+                path: { message_id: replyTo },
+                data: { msg_type: 'post', content },
+            })
+            : await this.client.im.message.create({
+                params: { receive_id_type: 'chat_id' },
+                data: { receive_id: chatId, msg_type: 'post', content },
+            });
+        return requireMessageId(resp, 'send post');
+    }
+    /** Upload an image and return the image_key. */
+    async uploadImage(imageBuffer) {
+        this._logOutgoing('uploadImage', `bytes=${imageBuffer.byteLength}`);
+        const resp = await this.client.im.image.create({
+            data: {
+                image_type: 'message',
+                image: imageBuffer,
+            },
+        });
+        const imageKey = resp?.image_key ?? resp?.data?.image_key;
+        if (!imageKey)
+            throw new Error('Image upload failed: no image_key returned');
+        return imageKey;
+    }
+    /** Upload a file and return the file_key. */
+    async uploadFile(fileBuffer, fileName) {
+        const ext = path.extname(fileName).toLowerCase().slice(1);
+        const fileType = (['pdf', 'doc', 'xls', 'ppt'].includes(ext) ? ext : 'stream');
+        this._logOutgoing('uploadFile', `file=${fileName} bytes=${fileBuffer.byteLength}`);
+        const resp = await this.client.im.file.create({
+            data: {
+                file_type: fileType,
+                file_name: fileName,
+                file: fileBuffer,
+            },
+        });
+        const fileKey = resp?.file_key ?? resp?.data?.file_key;
+        if (!fileKey)
+            throw new Error('File upload failed: no file_key returned');
+        return fileKey;
+    }
+    /** Upload and send a local file. */
+    async sendFile(chatId, filePath, opts = {}) {
+        const stat = fs.statSync(filePath);
+        if (stat.size > FILE_MAX_BYTES) {
+            throw new Error(`file too large (${(stat.size / 1024 / 1024).toFixed(1)}MB, max ${FILE_MAX_BYTES / 1024 / 1024}MB)`);
+        }
+        const content = fs.readFileSync(filePath);
+        const filename = path.basename(filePath);
+        const isPhoto = opts.asPhoto ?? PHOTO_EXTS.has(path.extname(filename).toLowerCase());
+        const caption = typeof opts.caption === 'string' ? opts.caption.trim() : '';
+        const replyTo = opts.replyTo ? String(opts.replyTo) : undefined;
+        if (isPhoto) {
+            try {
+                const imageKey = await this.uploadImage(content);
+                if (caption) {
+                    return await this.sendPost(String(chatId), buildPostContent([
+                        [{ tag: 'img', image_key: imageKey }],
+                        [{ tag: 'text', text: caption }],
+                    ]), { replyTo });
+                }
+                const msgContent = JSON.stringify({ image_key: imageKey });
+                this._logOutgoing('sendImage', `${replyTo ? `reply_to=${replyTo}` : `chat=${chatId}`} file=${filename}`);
+                const resp = replyTo
+                    ? await this.client.im.message.reply({ path: { message_id: replyTo }, data: { msg_type: 'image', content: msgContent } })
+                    : await this.client.im.message.create({ params: { receive_id_type: 'chat_id' }, data: { receive_id: String(chatId), msg_type: 'image', content: msgContent } });
+                return requireMessageId(resp, 'send image');
+            }
+            catch (err) {
+                if (isRetryableUploadError(err))
+                    throw err;
+            }
+        }
+        const fileKey = await this.uploadFile(content, filename);
+        const msgContent = JSON.stringify({ file_key: fileKey });
+        this._logOutgoing('sendFile', `${replyTo ? `reply_to=${replyTo}` : `chat=${chatId}`} file=${filename}`);
+        const resp = replyTo
+            ? await this.client.im.message.reply({ path: { message_id: replyTo }, data: { msg_type: 'file', content: msgContent } })
+            : await this.client.im.message.create({ params: { receive_id_type: 'chat_id' }, data: { receive_id: String(chatId), msg_type: 'file', content: msgContent } });
+        return requireMessageId(resp, 'send file');
+    }
+    // ========================================================================
+    // Download resources from received messages
+    // ========================================================================
+    async _downloadResource(messageId, fileKey, type, filename) {
+        const resp = await this.client.im.messageResource.get({
+            path: { message_id: messageId, file_key: fileKey },
+            params: { type },
+        });
+        const ext = type === 'image' ? '.jpg' : (filename ? path.extname(filename) : '.bin');
+        const name = filename || `feishu_${fileKey.slice(-8)}${ext}`;
+        const localPath = path.join(this.workdir, `_feishu_${name}`);
+        fs.mkdirSync(this.workdir, { recursive: true });
+        await resp.writeFile(localPath);
+        // Check downloaded file size
+        const stat = fs.statSync(localPath);
+        if (stat.size > FILE_MAX_BYTES) {
+            fs.rmSync(localPath, { force: true });
+            throw new Error(`file too large (${(stat.size / 1024 / 1024).toFixed(1)}MB, max ${FILE_MAX_BYTES / 1024 / 1024}MB)`);
+        }
+        return localPath;
+    }
+    // ========================================================================
+    // Internal helpers
+    // ========================================================================
+    _makeCtx(chatId, messageId, from, chatType, raw, replyToMessageId) {
+        return {
+            chatId,
+            messageId,
+            from,
+            chatType,
+            replyToMessageId: replyToMessageId || null,
+            reply: (text, opts) => this.send(chatId, text, { ...opts, replyTo: messageId || opts?.replyTo }),
+            editReply: (msgId, text, opts) => this.editMessage(chatId, msgId, text, opts),
+            channel: this,
+            raw,
+        };
+    }
+    _isAllowed(chatId) {
+        return this.allowedChatIds.size === 0 || this.allowedChatIds.has(chatId);
+    }
+    /**
+     * Add a chat to the in-memory `knownChats` set and persist it to setting.json
+     * so a future cold start (e.g. crash-respawn) can still address it. The
+     * persistence call is fire-and-forget — disk errors must not break receive.
+     */
+    _trackChat(chatId) {
+        if (this.knownChats.has(chatId))
+            return;
+        this.knownChats.add(chatId);
+        try {
+            recordKnownChatId('feishu', chatId);
+        }
+        catch { }
+    }
+    _isBotMentioned(msg) {
+        const mentions = msg.mentions || [];
+        if (!this.bot)
+            return mentions.length > 0;
+        return mentions.some((m) => {
+            const mentionId = m.id?.open_id || m.id?.app_id || '';
+            return mentionId === this.bot.id || m.name === this.bot.displayName;
+        });
+    }
+    _cleanMention(text) {
+        return text.replace(/@_user_\d+/g, '').trim();
+    }
+    /** Extract plain text from a rich text (post) message content. */
+    _extractPostText(content) {
+        const post = content.zh_cn || content.en_us || content;
+        const parts = [];
+        if (post.title)
+            parts.push(post.title);
+        const paragraphs = post.content || [];
+        for (const paragraph of paragraphs) {
+            if (!Array.isArray(paragraph))
+                continue;
+            const line = paragraph
+                .map((elem) => {
+                if (elem.tag === 'text')
+                    return elem.text || '';
+                if (elem.tag === 'a')
+                    return elem.text || elem.href || '';
+                if (elem.tag === 'at')
+                    return '';
+                return '';
+            })
+                .join('');
+            if (line.trim())
+                parts.push(line);
+        }
+        return parts.join('\n');
+    }
+    _debug(msg) {
+        this._log(msg, 'debug');
+    }
+    _log(msg, level = 'info') {
+        writeScopedLog('feishu', msg, { level });
+    }
+    _logOutgoing(action, meta) {
+        this._debug(`[send] ${action} ${meta}`);
+    }
+}