openclaw-lark-multi-agent 0.1.5 → 0.1.7

package/dist/feishu-bot.d.ts

@@ -74,6 +74,12 @@ export declare class FeishuBot {
     private cleanMentions;
     private stripLeadingCommandMentions;
     private replyMessage;
+    private extractBridgeAttachments;
+    private validateBridgeAttachmentPath;
+    private inferFeishuFileType;
+    private isImagePath;
+    private createFeishuDocFromMarkdown;
+    private sendBridgeAttachment;
     /**
      * Send a proactive message to a chat (not a reply).
      */

package/dist/feishu-bot.js

@@ -1,5 +1,9 @@
 import * as lark from "@larksuiteoapi/node-sdk";
+import { existsSync, readFileSync, statSync } from "fs";
+import { basename, extname, resolve } from "path";
+import { getBridgeAttachmentsDir } from "./paths.js";
 const MAX_BOT_STREAK = 10;
+const BRIDGE_ATTACHMENTS_DIR = getBridgeAttachmentsDir();
 /**
  * Manages a single Feishu bot instance.
  *
@@ -107,7 +111,12 @@ export class FeishuBot {
         await this.openclawClient.subscribeSession(sessionKey, async (text) => {
             try {
                 console.log(`[${this.config.name}] Proactive message for ${chatId.slice(-8)}`);
-                await this.sendMessage(chatId, text);
+                const parsed = this.extractBridgeAttachments(text);
+                if (parsed.text.trim())
+                    await this.sendMessage(chatId, parsed.text);
+                for (const attachment of parsed.attachments) {
+                    await this.sendBridgeAttachment(chatId, attachment);
+                }
             }
             catch (err) {
                 console.error(`[${this.config.name}] Failed to deliver proactive msg:`, err.message);
@@ -335,7 +344,7 @@ export class FeishuBot {
             // Single slash commands are handled by the bridge. Double slash commands were
             // already unescaped above and should pass through to OpenClaw instead.
             const isBridgeCommand = !commandText.startsWith("//");
-            const isCommand = isBridgeCommand && /^\/(help|status|compact|reset|verbose|free)/.test(cleanText.trim());
+            const isCommand = isBridgeCommand && /^\/(help|status|compact|reset|verbose|free|mute|mode)/.test(cleanText.trim());
             if (isCommand) {
                 // In group chats, bridge commands must be explicitly routed to this bot
                 // or @all. Do not let Free Discussion make a bot execute commands meant
@@ -357,7 +366,9 @@ export class FeishuBot {
                         `🧹 /compact — 压缩当前 bot 的 OpenClaw session`,
                         `🔄 /reset   — 重置当前 bot 的 OpenClaw session`,
                         `🔊 /verbose — 开关当前聊天里的 Tool Call 显示`,
-                        `🔓 /free [on|off|status] — 开关当前 bot 在当前群聊的 Free Discussion`,
+                        `🔓 /free   — 切换当前 bot 的 free 模式（不 @ 也可回复）`,
+                        `🤐 /mute   — 切换当前 bot 的 mute 模式（禁言，不转发 OpenClaw）`,
+                        `🎛️ /mode   — 查看当前 bot 在当前群聊的模式`,
                         `❓ /help    — 显示此帮助信息`,
                         ``,
                         `OpenClaw 原生命令（双斜杠，会转成单斜杠发给 OpenClaw）`,
@@ -416,32 +427,64 @@ export class FeishuBot {
                 }
                 if (cleanText.trim().startsWith("/free")) {
                     if (chatType === "p2p") {
-                        await this.replyMessage(messageId, "❌ Free Discussion 只在群聊中可用");
+                        await this.replyMessage(messageId, "❌ Free 模式只在群聊中可用");
                         markCommandSynced();
                         return;
                     }
-                    const parts = cleanText.trim().split(/\s+/);
-                    const arg = (parts[1] || "").toLowerCase();
-                    const isOn = this.store.getBotFreeDiscussion(this.config.name, chatId);
-                    const next = arg === "on" || arg === "true" || arg === "1"
-                        ? true
-                        : arg === "off" || arg === "false" || arg === "0"
-                            ? false
-                            : arg === "status"
-                                ? isOn
-                                : !isOn;
-                    if (arg !== "status")
-                        this.store.setBotFreeDiscussion(this.config.name, chatId, next);
-                    if (next) {
-                        await this.replyMessage(messageId, `🔓 ${this.config.name} Free Discussion 已开启\n只影响当前 Bot 在当前群聊的自由发言（连续 Bot 回复超过 ${MAX_BOT_STREAK} 轮将暂停，等待人类发言）`);
+                    const current = this.store.getBotMode(this.config.name, chatId);
+                    const next = current === "free" ? "normal" : "free";
+                    this.store.setBotMode(this.config.name, chatId, next);
+                    if (next === "free") {
+                        await this.replyMessage(messageId, `🔓 ${this.config.name} 已切换到 free 模式\n不需要 @ 也可以参与回复（连续 Bot 回复超过 ${MAX_BOT_STREAK} 轮将暂停，等待人类发言）`);
+                    }
+                    else {
+                        await this.replyMessage(messageId, `🔒 ${this.config.name} 已切换到 normal 模式\n只有明确 @ 我才会回复`);
+                    }
+                    markCommandSynced();
+                    return;
+                }
+                if (cleanText.trim().startsWith("/mute")) {
+                    if (chatType === "p2p") {
+                        await this.replyMessage(messageId, "❌ Mute 模式只在群聊中可用");
+                        markCommandSynced();
+                        return;
+                    }
+                    const current = this.store.getBotMode(this.config.name, chatId);
+                    const next = current === "mute" ? "normal" : "mute";
+                    this.store.setBotMode(this.config.name, chatId, next);
+                    if (next === "mute") {
+                        await this.replyMessage(messageId, `🤐 ${this.config.name} 已切换到 mute 模式\n普通消息、@所有人 都不会回复；明确 @ 我时只提示禁言中`);
+                    }
+                    else {
+                        await this.replyMessage(messageId, `🔒 ${this.config.name} 已解除 mute，回到 normal 模式\n只有明确 @ 我才会回复`);
+                    }
+                    markCommandSynced();
+                    return;
+                }
+                if (cleanText.trim().startsWith("/mode")) {
+                    if (chatType === "p2p") {
+                        await this.replyMessage(messageId, `🎛️ ${this.config.name} 当前模式：normal（私聊总是响应）`);
                     }
                     else {
-                        await this.replyMessage(messageId, `🔒 ${this.config.name} Free Discussion 已关闭\n只影响当前 Bot；群聊中需要 @ 指定 Bot 才会回复`);
+                        const mode = this.store.getBotMode(this.config.name, chatId);
+                        const desc = mode === "free" ? "不需要 @ 也可以参与回复" : mode === "mute" ? "禁言中；明确 @ 我时只提示禁言中" : "只有明确 @ 我才会回复";
+                        await this.replyMessage(messageId, `🎛️ ${this.config.name} 当前模式：${mode}\n${desc}`);
                     }
                     markCommandSynced();
                     return;
                 }
             }
+            // --- Mute mode: do not forward anything to OpenClaw. Only direct mentions get a local notice. ---
+            if (chatType !== "p2p" && !isBot && this.store.getBotMode(this.config.name, chatId) === "mute") {
+                if (this.isMentioned(message.mentions || [])) {
+                    await this.replyMessage(messageId, `🤐 ${this.config.name} 当前处于 mute 模式，发送 /mute 可解除`);
+                    if (insertedId > 0) {
+                        this.store.markSynced(this.config.name, chatId, insertedId);
+                        this.store.clearPendingTriggers(this.config.name, chatId, insertedId);
+                    }
+                }
+                return;
+            }
             // --- Should this bot respond? ---
             if (!this.shouldRespond(chatType, message, isBot, chatId, message.content))
                 return;
@@ -550,16 +593,22 @@ export class FeishuBot {
                 const maxId = Math.max(...allUnsynced.map((m) => m.id || 0));
                 this.store.markSynced(this.config.name, chatId, maxId);
                 this.store.clearPendingTriggers(this.config.name, chatId, maxId);
-                const trimmedReply = reply.trim();
+                const parsedReply = this.extractBridgeAttachments(reply);
+                const visibleReply = parsedReply.text;
+                const trimmedReply = visibleReply.trim();
                 const shouldReply = trimmedReply.length > 0 && trimmedReply.toUpperCase() !== "NO_REPLY";
+                const hasAttachments = parsedReply.attachments.length > 0;
                 // Record bot reply only if it is user-visible/context-worthy.
-                if (shouldReply) {
+                if (shouldReply || hasAttachments) {
+                    const storedContent = [visibleReply, ...parsedReply.attachments.map((a) => `[Attachment: ${a.type || "file"} ${a.path}]`)]
+                        .filter(Boolean)
+                        .join("\n");
                     const replyId = this.store.insert({
                         chatId,
                         messageId: `self-${this.config.name}-${Date.now()}`,
                         senderType: "bot",
                         senderName: this.config.name,
-                        content: reply,
+                        content: storedContent,
                         timestamp: Date.now(),
                     });
                     if (replyId > 0)
@@ -573,28 +622,33 @@ export class FeishuBot {
                 }
                 // Reply to the last human message on Feishu (ordered after tool msgs)
                 // Skip empty replies and explicit NO_REPLY responses
-                if (shouldReply && lastHuman.messageId) {
+                if ((shouldReply || hasAttachments) && lastHuman.messageId) {
                     if (triggerId && this.store.hasDeliveredReply(this.config.name, chatId, triggerId)) {
                         console.warn(`[${this.config.name}] Reply already delivered, skip duplicate for ${chatId.slice(-8)} msgId=${triggerId}`);
                     }
                     else {
                         await this.sendOrdered(chatId, async () => {
-                            try {
-                                await this.replyMessage(lastHuman.messageId, reply);
+                            if (shouldReply) {
+                                try {
+                                    await this.replyMessage(lastHuman.messageId, visibleReply);
+                                }
+                                catch (err) {
+                                    // Reply can fail for historical messages sent before this bot joined the chat
+                                    // (Feishu 230002: Bot/User can NOT be out of the chat). Fall back to a normal
+                                    // chat message so queue processing still completes.
+                                    console.warn(`[${this.config.name}] replyMessage failed, fallback to sendMessage:`, err.message);
+                                    await this.sendMessage(chatId, visibleReply);
+                                }
                             }
-                            catch (err) {
-                                // Reply can fail for historical messages sent before this bot joined the chat
-                                // (Feishu 230002: Bot/User can NOT be out of the chat). Fall back to a normal
-                                // chat message so queue processing still completes.
-                                console.warn(`[${this.config.name}] replyMessage failed, fallback to sendMessage:`, err.message);
-                                await this.sendMessage(chatId, reply);
+                            for (const attachment of parsedReply.attachments) {
+                                await this.sendBridgeAttachment(chatId, attachment);
                             }
                             if (triggerId)
                                 this.store.markDeliveredReply(this.config.name, chatId, triggerId, lastHuman.messageId);
                         });
                     }
                 }
-                console.log(`[${this.config.name}] [${new Date().toISOString()}] ${shouldReply ? 'Replied' : 'Skipped (empty/NO_REPLY)'} (${reply.length} chars)`);
+                console.log(`[${this.config.name}] [${new Date().toISOString()}] ${shouldReply || hasAttachments ? 'Replied' : 'Skipped (empty/NO_REPLY)'} (${reply.length} chars, attachments=${parsedReply.attachments.length})`);
                 // Replace ack reactions with DONE for all pending messages in this chat
                 const pendingAcks = this.pendingAckMessages.get(chatId) || [];
                 for (const ack of pendingAcks) {
@@ -643,9 +697,9 @@ export class FeishuBot {
         const anyBotMentioned = mentions.some((m) => this.mentionedBotName(m) !== null);
         if (anyBotMentioned && !this.isMentioned(mentions))
             return false;
-        // No bot mentioned: check free discussion mode
+        // No bot mentioned: check current per-bot mode
         if (chatId) {
-            if (this.store.getBotFreeDiscussion(this.config.name, chatId))
+            if (this.store.getBotMode(this.config.name, chatId) === "free")
                 return true;
         }
         // Default: don't respond without @
@@ -734,6 +788,137 @@ export class FeishuBot {
             });
         }
     }
+    extractBridgeAttachments(reply) {
+        const attachments = [];
+        const markerPattern = /<LMA_BRIDGE_ATTACHMENTS>([\s\S]*?)<\/LMA_BRIDGE_ATTACHMENTS>/g;
+        let text = reply.replace(markerPattern, (_match, jsonText) => {
+            try {
+                const parsed = JSON.parse(String(jsonText).trim());
+                const rawAttachments = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.attachments) ? parsed.attachments : [parsed];
+                for (const item of rawAttachments) {
+                    if (!item || typeof item.path !== "string")
+                        continue;
+                    attachments.push({
+                        type: item.type === "image" || item.type === "document" || item.type === "file" ? item.type : undefined,
+                        path: item.path,
+                        caption: typeof item.caption === "string" ? item.caption : undefined,
+                    });
+                }
+            }
+            catch (err) {
+                console.warn(`[${this.config.name}] Failed to parse bridge attachment marker:`, err.message);
+            }
+            return "";
+        }).trim();
+        return { text, attachments };
+    }
+    validateBridgeAttachmentPath(filePath) {
+        const resolvedPath = resolve(filePath);
+        const allowedRoot = resolve(BRIDGE_ATTACHMENTS_DIR);
+        if (!(resolvedPath === allowedRoot || resolvedPath.startsWith(allowedRoot + "/"))) {
+            throw new Error(`Attachment path outside allowed directory: ${resolvedPath}`);
+        }
+        if (!existsSync(resolvedPath))
+            throw new Error(`Attachment file not found: ${resolvedPath}`);
+        const stats = statSync(resolvedPath);
+        if (!stats.isFile())
+            throw new Error(`Attachment path is not a file: ${resolvedPath}`);
+        if (stats.size <= 0)
+            throw new Error(`Attachment file is empty: ${resolvedPath}`);
+        if (stats.size > 30 * 1024 * 1024)
+            throw new Error(`Attachment file too large (>30MB): ${resolvedPath}`);
+        return resolvedPath;
+    }
+    inferFeishuFileType(filePath) {
+        const ext = extname(filePath).toLowerCase();
+        if (ext === ".pdf")
+            return "pdf";
+        if ([".doc", ".docx"].includes(ext))
+            return "doc";
+        if ([".xls", ".xlsx", ".csv"].includes(ext))
+            return "xls";
+        if ([".ppt", ".pptx"].includes(ext))
+            return "ppt";
+        return "stream";
+    }
+    isImagePath(filePath) {
+        return [".jpg", ".jpeg", ".png", ".webp", ".gif", ".tiff", ".bmp", ".ico"].includes(extname(filePath).toLowerCase());
+    }
+    async createFeishuDocFromMarkdown(filePath) {
+        const rawTitle = basename(filePath).replace(/\.[^.]+$/, "").trim() || "Markdown Document";
+        const markdown = readFileSync(filePath, "utf8");
+        const docx = this.client.docx;
+        const created = await docx.document.create({ data: { title: rawTitle } });
+        const documentId = created?.data?.document?.document_id || created?.document?.document_id;
+        const revisionId = created?.data?.document?.revision_id || created?.document?.revision_id;
+        if (!documentId)
+            throw new Error(`Feishu doc create returned no document_id for ${filePath}`);
+        const converted = await docx.document.convert({ data: { content_type: "markdown", content: markdown } });
+        const convertedData = converted?.data || converted;
+        const blocks = convertedData?.blocks || [];
+        const firstLevelBlockIds = convertedData?.first_level_block_ids || [];
+        if (Array.isArray(blocks) && blocks.length > 0) {
+            await docx.documentBlockDescendant.create({
+                path: { document_id: documentId, block_id: documentId },
+                data: {
+                    children_id: firstLevelBlockIds,
+                    descendants: blocks,
+                    document_revision_id: revisionId,
+                },
+            });
+        }
+        return { title: rawTitle, url: `https://www.feishu.cn/docx/${documentId}` };
+    }
+    async sendBridgeAttachment(chatId, attachment) {
+        const filePath = this.validateBridgeAttachmentPath(attachment.path);
+        const type = attachment.type || (this.isImagePath(filePath) ? "image" : "file");
+        if (type === "document" && extname(filePath).toLowerCase() === ".md") {
+            const doc = await this.createFeishuDocFromMarkdown(filePath);
+            const caption = attachment.caption?.trim() || `飞书文档：${doc.title}`;
+            await this.sendMessage(chatId, `${caption}
+${doc.url}`);
+            return;
+        }
+        if (attachment.caption?.trim())
+            await this.sendMessage(chatId, attachment.caption.trim());
+        if (type === "image") {
+            if (statSync(filePath).size > 10 * 1024 * 1024)
+                throw new Error(`Image too large (>10MB): ${filePath}`);
+            const uploaded = await this.client.im.image.create({
+                data: { image_type: "message", image: readFileSync(filePath) },
+            });
+            const imageKey = uploaded?.image_key || uploaded?.data?.image_key;
+            if (!imageKey)
+                throw new Error(`Feishu image upload returned no image_key for ${filePath}`);
+            await this.client.im.message.create({
+                params: { receive_id_type: "chat_id" },
+                data: {
+                    receive_id: chatId,
+                    content: JSON.stringify({ image_key: imageKey }),
+                    msg_type: "image",
+                },
+            });
+            return;
+        }
+        const uploaded = await this.client.im.file.create({
+            data: {
+                file_type: this.inferFeishuFileType(filePath),
+                file_name: basename(filePath),
+                file: readFileSync(filePath),
+            },
+        });
+        const fileKey = uploaded?.file_key || uploaded?.data?.file_key;
+        if (!fileKey)
+            throw new Error(`Feishu file upload returned no file_key for ${filePath}`);
+        await this.client.im.message.create({
+            params: { receive_id_type: "chat_id" },
+            data: {
+                receive_id: chatId,
+                content: JSON.stringify({ file_key: fileKey }),
+                msg_type: "file",
+            },
+        });
+    }
     /**
      * Send a proactive message to a chat (not a reply).
      */
@@ -849,7 +1034,7 @@ export class FeishuBot {
         const sessionExists = session ? "✅ 活跃" : "⏳ 未初始化";
         const status = session?.status || "unknown";
         const verboseStatus = this.store.getBotVerbose(this.config.name, chatId) ? "🔊 开启" : "🔇 关闭";
-        const freeStatus = this.store.getBotFreeDiscussion(this.config.name, chatId) ? "🔓 开启" : "🔒 关闭";
+        const mode = chatType === "p2p" ? "normal" : this.store.getBotMode(this.config.name, chatId);
         const statusText = [
             `📊 ${this.config.name} Bot Status`,
             `━━━━━━━━━━━━━━━━━━`,
@@ -862,7 +1047,7 @@ export class FeishuBot {
             `🧮 上下文: ${fmtK(totalTokens)} / ${fmtK(contextTokens)} (${usedPct}%)${tokenNote}`,
             `📥 输入: ${fmtK(inputTokens)} | 📤 输出: ${fmtK(outputTokens)}`,
             `🔧 Verbose: ${verboseStatus}`,
-            `💬 Free Discussion: ${freeStatus}`,
+            `🎛️ Mode: ${mode}`,
         ].join("\n");
         await this.replyMessage(messageId, statusText);
     }

package/dist/message-store.d.ts

@@ -1,3 +1,4 @@
+export type BotChatMode = "normal" | "free" | "mute";
 export interface ChatInfo {
     chatId: string;
     chatType: "p2p" | "group";
@@ -8,7 +9,7 @@ export interface ChatInfo {
     memberNames: string;
     /** Which bot owns this chat (for p2p isolation) */
     ownerBot: string;
-    /** Free discussion mode (group chat: all bots respond without @) */
+    /** Legacy chat-level free discussion flag; per-bot mode is authoritative. */
     freeDiscussion: boolean;
     verbose: boolean;
     updatedAt: number;
@@ -58,6 +59,8 @@ export declare class MessageStore {
     setVerbose(chatId: string, verbose: boolean): void;
     setBotVerbose(botName: string, chatId: string, verbose: boolean): void;
     getBotVerbose(botName: string, chatId: string): boolean;
+    setBotMode(botName: string, chatId: string, mode: BotChatMode): void;
+    getBotMode(botName: string, chatId: string): BotChatMode;
     setBotFreeDiscussion(botName: string, chatId: string, on: boolean): void;
     getBotFreeDiscussion(botName: string, chatId: string): boolean;
     getChatInfo(chatId: string): ChatInfo | null;

package/dist/message-store.js

@@ -76,6 +76,7 @@ export class MessageStore {
         chat_id TEXT NOT NULL,
         verbose INTEGER NOT NULL DEFAULT 0,
         free_discussion INTEGER NOT NULL DEFAULT 0,
+        mode TEXT NOT NULL DEFAULT 'normal',
         updated_at INTEGER NOT NULL DEFAULT 0,
         PRIMARY KEY (bot_name, chat_id)
       );
@@ -108,6 +109,18 @@ export class MessageStore {
         catch {
             // Column already exists
         }
+        // Migration: replace independent free/mute booleans with one mutually exclusive mode.
+        try {
+            this.db.exec(`ALTER TABLE bot_chat_settings ADD COLUMN mode TEXT NOT NULL DEFAULT 'normal'`);
+        }
+        catch {
+            // Column already exists
+        }
+        this.db.exec(`
+      UPDATE bot_chat_settings
+      SET mode = 'free'
+      WHERE free_discussion = 1 AND (mode IS NULL OR mode = '' OR mode = 'normal')
+    `);
     }
     /**
      * Insert a message. Returns the auto-increment id, or -1 if duplicate.
@@ -278,21 +291,31 @@ export class MessageStore {
     `).get(botName, chatId);
         return !!row?.verbose;
     }
-    setBotFreeDiscussion(botName, chatId, on) {
+    setBotMode(botName, chatId, mode) {
+        const freeDiscussion = mode === "free" ? 1 : 0;
         this.db.prepare(`
-      INSERT INTO bot_chat_settings (bot_name, chat_id, free_discussion, updated_at)
-      VALUES (?, ?, ?, ?)
+      INSERT INTO bot_chat_settings (bot_name, chat_id, mode, free_discussion, updated_at)
+      VALUES (?, ?, ?, ?, ?)
       ON CONFLICT (bot_name, chat_id) DO UPDATE SET
+        mode = excluded.mode,
         free_discussion = excluded.free_discussion,
         updated_at = excluded.updated_at
-    `).run(botName, chatId, on ? 1 : 0, Date.now());
+    `).run(botName, chatId, mode, freeDiscussion, Date.now());
     }
-    getBotFreeDiscussion(botName, chatId) {
+    getBotMode(botName, chatId) {
         const row = this.db.prepare(`
-      SELECT free_discussion FROM bot_chat_settings
+      SELECT mode, free_discussion FROM bot_chat_settings
       WHERE bot_name = ? AND chat_id = ?
     `).get(botName, chatId);
-        return !!row?.free_discussion;
+        if (row?.mode === "free" || row?.mode === "mute" || row?.mode === "normal")
+            return row.mode;
+        return row?.free_discussion ? "free" : "normal";
+    }
+    setBotFreeDiscussion(botName, chatId, on) {
+        this.setBotMode(botName, chatId, on ? "free" : "normal");
+    }
+    getBotFreeDiscussion(botName, chatId) {
+        return this.getBotMode(botName, chatId) === "free";
     }
     getChatInfo(chatId) {
         const row = this.db.prepare(`SELECT * FROM chat_info WHERE chat_id = ?`).get(chatId);

package/dist/openclaw-client.d.ts

@@ -78,6 +78,8 @@ export declare class OpenClawClient {
         deliver?: boolean;
         timeoutMs?: number;
     }): Promise<string>;
+    private shouldInjectBridgeAttachmentHint;
+    private bridgeAttachmentHint;
     /**
      * Build and send a context catch-up message followed by the actual message.
      *

package/dist/openclaw-client.js

@@ -2,6 +2,8 @@ import WebSocket from "ws";
 import { randomUUID } from "crypto";
 import { readFileSync } from "fs";
 import { basename, extname } from "path";
+import { getBridgeAttachmentsDir } from "./paths.js";
+const BRIDGE_ATTACHMENTS_DIR = getBridgeAttachmentsDir();
 /**
  * OpenClaw Gateway WebSocket client.
  * Full agent pipeline — tools, memory, skills, context management by OpenClaw.
@@ -502,6 +504,16 @@ export class OpenClawClient {
             this.releaseSuppressedSessionKeysAfter(suppressedKeys, 30000);
         }
     }
+    shouldInjectBridgeAttachmentHint(text) {
+        return /发送|发到|发给|传|上传|附件|文件|文档|图片|图像|照片|生成图|做张图|画张图|导出|保存|pdf|docx?|xlsx?|pptx?|markdown|\bmd\b/i.test(text);
+    }
+    bridgeAttachmentHint(text) {
+        if (!this.shouldInjectBridgeAttachmentHint(text))
+            return "";
+        return `
+
+[Bridge attachment capability hint: This is an OpenClaw Lark Multi-Agent bridge session. You cannot send Feishu files/images directly from inside OpenClaw. Do NOT call message, sessions_send, Feishu tools, or proactive send tools for this request. If the user asks you to send an image/file/document to Feishu, only create the local file under ${BRIDGE_ATTACHMENTS_DIR}/ and include this exact marker at the very end of your final reply (do not explain or expose the marker as normal text): <LMA_BRIDGE_ATTACHMENTS>{"attachments":[{"type":"image|file|document","path":"/absolute/path","caption":"optional"}]}</LMA_BRIDGE_ATTACHMENTS>. The bridge layer will parse this marker and send the attachment. Use type=image for images; use type=document for Markdown documents (.md) so the bridge creates a Feishu cloud document and sends its link; use type=file for other ordinary files.]`;
+    }
     /**
      * Build and send a context catch-up message followed by the actual message.
      *
@@ -523,11 +535,12 @@ export class OpenClawClient {
         const mediaInstruction = attachments.length > 0
             ? "\n\n[Media note: Image attachments are included with this message. If your model can inspect images directly, use the attached image input. If it cannot, use the image tool on the provided media/attachment path; do not try unrelated network or model-provider workarounds.]"
             : "";
+        const bridgeAttachmentHint = this.bridgeAttachmentHint(params.currentMessage);
         if (params.unsyncedMessages.length === 0) {
             // No context to catch up, send directly
             return this.chatSend({
                 sessionKey: params.sessionKey,
-                message: params.currentMessage + mediaInstruction,
+                message: params.currentMessage + mediaInstruction + bridgeAttachmentHint,
                 attachments,
                 deliver: params.deliver,
                 timeoutMs: params.timeoutMs,
@@ -549,7 +562,7 @@ export class OpenClawClient {
             `[${params.currentSenderName}]: ${params.currentMessage}`;
         return this.chatSend({
             sessionKey: params.sessionKey,
-            message: combined + mediaInstruction,
+            message: combined + mediaInstruction + bridgeAttachmentHint,
             attachments,
             deliver: params.deliver,
             timeoutMs: params.timeoutMs,

package/dist/paths.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Runtime state defaults to the user's home directory but can be overridden
+ * for packaged deployments, tests, containers, or systemd installations.
+ */
+export declare function getStateDir(): string;
+export declare function getBridgeAttachmentsDir(): string;

package/dist/paths.js

@@ -0,0 +1,12 @@
+import { homedir } from "os";
+import { resolve } from "path";
+/**
+ * Runtime state defaults to the user's home directory but can be overridden
+ * for packaged deployments, tests, containers, or systemd installations.
+ */
+export function getStateDir() {
+    return resolve(process.env.OPENCLAW_LARK_MULTI_AGENT_STATE_DIR || resolve(homedir(), ".openclaw/openclaw-lark-multi-agent"));
+}
+export function getBridgeAttachmentsDir() {
+    return resolve(process.env.OPENCLAW_LARK_MULTI_AGENT_ATTACHMENTS_DIR || resolve(getStateDir(), "attachments"));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-lark-multi-agent",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Multi-bot Lark/Feishu bridge for OpenClaw, with per-bot model routing and isolated sessions",
   "type": "module",
   "scripts": {