openclaw-plugin-wecom 1.0.2 → 1.1.0

package/README.md

@@ -9,6 +9,7 @@
 - 🌊 **Streaming Output**: Built on WeCom's latest AI bot streaming mechanism for smooth typewriter-style responses.
 - 🤖 **Dynamic Agent Management**: Automatically creates isolated agents per direct message user or group chat, with independent workspaces and conversation contexts.
 - 👥 **Deep Group Chat Integration**: Supports group message parsing with @mention triggering.
+- 🖼️ **Image Support**: Automatic base64 encoding and sending of local images (screenshots, generated images) without requiring additional configuration.
 - 🛠️ **Command Enhancement**: Built-in commands (e.g., `/new` for new sessions, `/status` for status) with allowlist configuration.
 - 🔒 **Security & Authentication**: Full support for WeCom message encryption/decryption, URL verification, and sender validation.
 - ⚡ **High-Performance Async Processing**: Asynchronous message architecture ensures responsive gateway even during long AI inference.
@@ -211,6 +212,23 @@ Prevent regular users from executing sensitive Gateway management commands throu
 
 **Reason:** OpenClaw tries to auto-enable built-in channel configurations with the id `wecom`. Adding `deny` prevents this auto-enablement, ensuring only the `openclaw-plugin-wecom` plugin is used.
 
+### Q: How does image sending work?
+
+**A:** The plugin automatically handles images generated by OpenClaw (such as browser screenshots):
+
+- **Local images** (from `~/.openclaw/media/`) are automatically encoded to base64 and sent via WeCom's `msg_item` API
+- **Image constraints**: Max 2MB per image, supports JPG and PNG formats, up to 10 images per message
+- **No configuration needed**: Works out of the box with tools like browser screenshot
+- Images appear when the AI completes its response (streaming doesn't support incremental image sending)
+
+**Example:**
+```
+User: "Take a screenshot of GitHub homepage"
+AI: [Takes screenshot] → Image displays properly in WeCom ✅
+```
+
+If an image fails to process (size limit, invalid format), the text response will still be delivered and an error will be logged.
+
 ### Q: How to configure auth token for public-facing OpenClaw with WeCom callbacks?
 
 **A:** WeCom bot **does not need** OpenClaw's Gateway Auth Token.

package/README_ZH.md

@@ -9,6 +9,7 @@
 - 🌊 **流式输出 (Streaming)**: 基于企业微信最新的 AI 机器人流式分片机制，实现流畅的打字机式回复体验。
 - 🤖 **动态 Agent 管理**: 默认按"每个私聊用户 / 每个群聊"自动创建独立 Agent。每个 Agent 拥有独立的工作区与对话上下文，实现更强的数据隔离。
 - 👥 **群聊深度集成**: 支持群聊消息解析，可通过 @提及（At-mention）精准触发机器人响应。
+- 🖼️ **图片支持**: 自动将本地图片（截图、生成的图像）进行 base64 编码并发送，无需额外配置。
 - 🛠️ **指令增强**: 内置常用指令支持（如 `/new` 开启新会话、`/status` 查看状态等），并提供指令白名单配置功能。
 - 🔒 **安全与认证**: 完整支持企业微信消息加解密、URL 验证及发送者身份校验。
 - ⚡ **高性能异步处理**: 采用异步消息处理架构，确保即使在长耗时 AI 推理过程中，企业微信网关也能保持高响应性。
@@ -211,6 +212,23 @@ npm install openclaw-plugin-wecom
 
 **原因：** OpenClaw 会尝试自动启用 channel id 为 `wecom` 的内置插件配置，添加 `deny` 可以防止这种自动启用，确保只使用 `openclaw-plugin-wecom` 插件。
 
+### Q: 图片发送是如何工作的？
+
+**A:** 插件会自动处理 OpenClaw 生成的图片（如浏览器截图）：
+
+- **本地图片**（来自 `~/.openclaw/media/`）会自动进行 base64 编码，通过企业微信 `msg_item` API 发送
+- **图片限制**：单张图片最大 2MB，支持 JPG 和 PNG 格式，每条消息最多 10 张图片
+- **无需配置**：开箱即用，配合浏览器截图等工具自动生效
+- 图片会在 AI 完成回复后显示（流式输出不支持增量发送图片）
+
+**示例：**
+```
+用户："帮我截个 GitHub 首页的图"
+AI：[执行截图] → 图片在企业微信中正常显示 ✅
+```
+
+如果图片处理失败（超出大小限制、格式不支持等），文本回复仍会正常发送，错误信息会记录在日志中。
+
 ### Q: OpenClaw 开放公网需要 auth token，企业微信回调如何配置？
 
 **A:** 企业微信机器人**不需要**配置 OpenClaw 的 Gateway Auth Token。

package/image-processor.js

@@ -0,0 +1,179 @@
+import { readFile } from "fs/promises";
+import { createHash } from "crypto";
+import { logger } from "./logger.js";
+
+/**
+ * Image Processing Module for WeCom
+ *
+ * Handles loading, validating, and encoding images for WeCom msg_item
+ * Supports JPG and PNG formats up to 2MB
+ */
+
+// Image format signatures (magic bytes)
+const IMAGE_SIGNATURES = {
+    JPG: [0xFF, 0xD8, 0xFF],
+    PNG: [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A],
+};
+
+// 2MB size limit (before base64 encoding)
+const MAX_IMAGE_SIZE = 2 * 1024 * 1024;
+
+/**
+ * Load image file from filesystem
+ * @param {string} filePath - Absolute path to image file
+ * @returns {Promise<Buffer>} Image data buffer
+ * @throws {Error} If file not found or cannot be read
+ */
+export async function loadImageFromPath(filePath) {
+    try {
+        logger.debug("Loading image from path", { filePath });
+        const buffer = await readFile(filePath);
+        logger.debug("Image loaded successfully", {
+            filePath,
+            size: buffer.length
+        });
+        return buffer;
+    } catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Image file not found: ${filePath}`);
+        } else if (error.code === "EACCES") {
+            throw new Error(`Permission denied reading image: ${filePath}`);
+        } else {
+            throw new Error(`Failed to read image file: ${error.message}`);
+        }
+    }
+}
+
+/**
+ * Convert buffer to base64 string
+ * @param {Buffer} buffer - Image data buffer
+ * @returns {string} Base64-encoded string
+ */
+export function encodeImageToBase64(buffer) {
+    return buffer.toString("base64");
+}
+
+/**
+ * Calculate MD5 checksum of buffer
+ * @param {Buffer} buffer - Image data buffer
+ * @returns {string} MD5 hash in hexadecimal
+ */
+export function calculateMD5(buffer) {
+    return createHash("md5").update(buffer).digest("hex");
+}
+
+/**
+ * Validate image size is within limits
+ * @param {Buffer} buffer - Image data buffer
+ * @throws {Error} If size exceeds 2MB limit
+ */
+export function validateImageSize(buffer) {
+    const sizeBytes = buffer.length;
+    const sizeMB = (sizeBytes / 1024 / 1024).toFixed(2);
+
+    if (sizeBytes > MAX_IMAGE_SIZE) {
+        throw new Error(
+            `Image size ${sizeMB}MB exceeds 2MB limit (actual: ${sizeBytes} bytes)`
+        );
+    }
+
+    logger.debug("Image size validated", { sizeBytes, sizeMB });
+}
+
+/**
+ * Detect image format from magic bytes
+ * @param {Buffer} buffer - Image data buffer
+ * @returns {string} Format: "JPG" or "PNG"
+ * @throws {Error} If format is not supported
+ */
+export function detectImageFormat(buffer) {
+    // Check PNG signature
+    if (buffer.length >= IMAGE_SIGNATURES.PNG.length) {
+        const isPNG = IMAGE_SIGNATURES.PNG.every(
+            (byte, index) => buffer[index] === byte
+        );
+        if (isPNG) {
+            logger.debug("Image format detected: PNG");
+            return "PNG";
+        }
+    }
+
+    // Check JPG signature
+    if (buffer.length >= IMAGE_SIGNATURES.JPG.length) {
+        const isJPG = IMAGE_SIGNATURES.JPG.every(
+            (byte, index) => buffer[index] === byte
+        );
+        if (isJPG) {
+            logger.debug("Image format detected: JPG");
+            return "JPG";
+        }
+    }
+
+    // Unknown format
+    const header = buffer.slice(0, 16).toString("hex");
+    throw new Error(
+        `Unsupported image format. Only JPG and PNG are supported. ` +
+        `File header: ${header}`
+    );
+}
+
+/**
+ * Complete image processing pipeline
+ *
+ * Loads image from filesystem, validates format and size,
+ * then encodes to base64 and calculates MD5 checksum.
+ *
+ * @param {string} filePath - Absolute path to image file
+ * @returns {Promise<Object>} Processed image data
+ * @returns {string} return.base64 - Base64-encoded image data
+ * @returns {string} return.md5 - MD5 checksum
+ * @returns {string} return.format - Image format (JPG or PNG)
+ * @returns {number} return.size - Original size in bytes
+ *
+ * @throws {Error} If any step fails (file not found, invalid format, size exceeded, etc.)
+ *
+ * @example
+ * const result = await prepareImageForMsgItem('/path/to/image.jpg');
+ * // Returns: { base64: "...", md5: "...", format: "JPG", size: 123456 }
+ */
+export async function prepareImageForMsgItem(filePath) {
+    logger.debug("Starting image processing pipeline", { filePath });
+
+    try {
+        // Step 1: Load image
+        const buffer = await loadImageFromPath(filePath);
+
+        // Step 2: Validate size
+        validateImageSize(buffer);
+
+        // Step 3: Detect format
+        const format = detectImageFormat(buffer);
+
+        // Step 4: Encode to base64
+        const base64 = encodeImageToBase64(buffer);
+
+        // Step 5: Calculate MD5
+        const md5 = calculateMD5(buffer);
+
+        logger.info("Image processed successfully", {
+            filePath,
+            format,
+            size: buffer.length,
+            md5,
+            base64Length: base64.length
+        });
+
+        return {
+            base64,
+            md5,
+            format,
+            size: buffer.length
+        };
+    } catch (error) {
+        logger.error("Image processing failed", {
+            filePath,
+            error: error.message
+        });
+        throw error;
+    }
+}

package/index.js

@@ -184,7 +184,7 @@ const wecomChannelPlugin = {
     chatTypes: ["direct", "group"],  // 支持私聊和群聊
     reactions: false,
     threads: false,
-    media: false,
+    media: true,  // Supports image sending via base64 encoding
     nativeCommands: false,
     blockStreaming: true, // WeCom AI Bot uses stream response format
   },
@@ -264,8 +264,60 @@ const wecomChannelPlugin = {
       const streamId = activeStreams.get(userId);
 
       if (streamId && streamManager.hasStream(streamId)) {
+        // Check if mediaUrl is a local path (sandbox: prefix or absolute path)
+        const isLocalPath = mediaUrl.startsWith("sandbox:") || mediaUrl.startsWith("/");
+
+        if (isLocalPath) {
+          // Convert sandbox: URLs to absolute paths
+          // Support both sandbox:/ and sandbox:// formats
+          const absolutePath = mediaUrl
+            .replace(/^sandbox:\/\//, "")
+            .replace(/^sandbox:\//, "");
+
+          logger.debug("Queueing local image for stream", {
+            userId,
+            streamId,
+            mediaUrl,
+            absolutePath
+          });
+
+          // Queue the image for processing when stream finishes
+          const queued = streamManager.queueImage(streamId, absolutePath);
+
+          if (queued) {
+            // Append text content to stream (without markdown image)
+            if (text) {
+              const stream = streamManager.getStream(streamId);
+              const separator = stream && stream.content.length > 0 ? "\n\n" : "";
+              streamManager.appendStream(streamId, separator + text);
+            }
+
+            // Append placeholder indicating image will follow
+            const imagePlaceholder = "\n\n[图片]";
+            streamManager.appendStream(streamId, imagePlaceholder);
+
+            return {
+              channel: "wecom",
+              messageId: `msg_stream_img_${Date.now()}`,
+            };
+          } else {
+            logger.warn("Failed to queue image, falling back to markdown", {
+              userId,
+              streamId,
+              mediaUrl
+            });
+            // Fallback to old behavior
+          }
+        }
+
+        // OLD BEHAVIOR: For external URLs or if queueing failed, use markdown
         const content = text ? `${text}\n\n![image](${mediaUrl})` : `![image](${mediaUrl})`;
-        logger.debug("Appending outbound media to stream", { userId, streamId, mediaUrl });
+        logger.debug("Appending outbound media to stream (markdown)", {
+          userId,
+          streamId,
+          mediaUrl
+        });
+
         // 使用 appendStream 追加内容
         const stream = streamManager.getStream(streamId);
         const separator = stream && stream.content.length > 0 ? "\n\n" : "";
@@ -412,10 +464,10 @@ async function wecomHttpHandler(req, res) {
         nonce,
         account: target.account,
         config: target.config,
-      }).catch((err) => {
+      }).catch(async (err) => {
         logger.error("WeCom message processing failed", { error: err.message });
         // 即使失败也要标记流为完成
-        streamManager.finishStream(streamId);
+        await streamManager.finishStream(streamId);
       });
 
       return true;
@@ -450,7 +502,11 @@ async function wecomHttpHandler(req, res) {
         stream.content,
         stream.finished,
         timestamp,
-        nonce
+        nonce,
+        // Pass msgItem when stream is finished and has images
+        stream.finished && stream.msgItem.length > 0
+          ? { msgItem: stream.msgItem }
+          : {}
       );
 
       res.writeHead(200, { "Content-Type": "application/json" });
@@ -495,7 +551,7 @@ async function wecomHttpHandler(req, res) {
         const streamId = `welcome_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
         streamManager.createStream(streamId);
         streamManager.appendStream(streamId, welcomeMessage);
-        streamManager.finishStream(streamId);
+        await streamManager.finishStream(streamId);
 
         const streamResponse = webhook.buildStreamResponse(
           streamId,
@@ -592,7 +648,7 @@ async function processInboundMessage({ message, streamId, timestamp, nonce, acco
     // 通过流式响应返回拦截消息
     if (streamId) {
       streamManager.appendStream(streamId, cmdConfig.blockMessage);
-      streamManager.finishStream(streamId);
+      await streamManager.finishStream(streamId);
       activeStreams.delete(streamKey);
     }
     return;
@@ -713,15 +769,15 @@ async function processInboundMessage({ message, streamId, timestamp, nonce, acco
 
         // 如果是最终回复,标记流为完成
         if (streamId && info.kind === "final") {
-          streamManager.finishStream(streamId);
+          await streamManager.finishStream(streamId);
           logger.info("WeCom stream finished", { streamId });
         }
       },
-      onError: (err, info) => {
+      onError: async (err, info) => {
         logger.error("WeCom reply failed", { error: err.message, kind: info.kind });
         // 发生错误时也标记流为完成
         if (streamId) {
-          streamManager.finishStream(streamId);
+          await streamManager.finishStream(streamId);
         }
       },
     },
@@ -729,7 +785,7 @@ async function processInboundMessage({ message, streamId, timestamp, nonce, acco
 
   // 确保在dispatch完成后标记流为完成（兜底机制）
   if (streamId) {
-    streamManager.finishStream(streamId);
+    await streamManager.finishStream(streamId);
     activeStreams.delete(streamKey);  // 清理活跃流映射
     logger.info("WeCom stream finished (dispatch complete)", { streamId });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "openclaw-plugin-wecom",
-    "version": "1.0.2",
+    "version": "1.1.0",
     "description": "Enterprise WeChat AI Bot channel plugin for OpenClaw",
     "type": "module",
     "main": "index.js",
@@ -9,6 +9,7 @@
         "client.js",
         "crypto.js",
         "dynamic-agent.js",
+        "image-processor.js",
         "logger.js",
         "README.md",
         "README_ZH.md",
@@ -47,7 +48,7 @@
     "keywords": [
         "openclaw",
         "wecom",
-        "wecom",
+        "enterprise-wechat",
         "chat",
         "plugin"
     ],

package/stream-manager.js

@@ -1,4 +1,5 @@
 import { logger } from "./logger.js";
+import { prepareImageForMsgItem } from "./image-processor.js";
 
 /**
  * 流式消息状态管理器
@@ -6,7 +7,7 @@ import { logger } from "./logger.js";
  */
 class StreamManager {
     constructor() {
-        // streamId -> { content: string, finished: boolean, updatedAt: number, feedbackId: string|null, msgItem: Array }
+        // streamId -> { content: string, finished: boolean, updatedAt: number, feedbackId: string|null, msgItem: Array, pendingImages: Array }
         this.streams = new Map();
         this._cleanupInterval = null;
     }
@@ -42,6 +43,7 @@ class StreamManager {
             updatedAt: Date.now(),
             feedbackId: options.feedbackId || null,  // 用户反馈追踪
             msgItem: [],  // 图文混排消息列表
+            pendingImages: [],  // 待处理的图片路径列表
         });
         return streamId;
     }
@@ -117,9 +119,101 @@ class StreamManager {
     }
 
     /**
-     * 标记流为完成状态
+     * Queue image for inclusion when stream finishes
+     * @param {string} streamId - 流ID
+     * @param {string} imagePath - 图片绝对路径
+     * @returns {boolean} 是否成功队列
      */
-    finishStream(streamId) {
+    queueImage(streamId, imagePath) {
+        this.startCleanup();
+        const stream = this.streams.get(streamId);
+        if (!stream) {
+            logger.warn("Stream not found for queueImage", { streamId });
+            return false;
+        }
+
+        stream.pendingImages.push({
+            path: imagePath,
+            queuedAt: Date.now()
+        });
+
+        logger.debug("Image queued for stream", {
+            streamId,
+            imagePath,
+            totalQueued: stream.pendingImages.length
+        });
+
+        return true;
+    }
+
+    /**
+     * Process all pending images and build msgItem array
+     * @param {string} streamId - 流ID
+     * @returns {Promise<Array>} msg_item 数组
+     */
+    async processPendingImages(streamId) {
+        const stream = this.streams.get(streamId);
+        if (!stream || stream.pendingImages.length === 0) {
+            return [];
+        }
+
+        logger.debug("Processing pending images", {
+            streamId,
+            count: stream.pendingImages.length
+        });
+
+        const msgItems = [];
+
+        for (const img of stream.pendingImages) {
+            try {
+                // Limit to 10 images per WeCom API spec
+                if (msgItems.length >= 10) {
+                    logger.warn("Stream exceeded 10 image limit, truncating", {
+                        streamId,
+                        total: stream.pendingImages.length,
+                        processed: msgItems.length
+                    });
+                    break;
+                }
+
+                const processed = await prepareImageForMsgItem(img.path);
+                msgItems.push({
+                    msgtype: "image",
+                    image: {
+                        base64: processed.base64,
+                        md5: processed.md5
+                    }
+                });
+
+                logger.debug("Image processed successfully", {
+                    streamId,
+                    imagePath: img.path,
+                    format: processed.format,
+                    size: processed.size
+                });
+            } catch (error) {
+                logger.error("Failed to process image for stream", {
+                    streamId,
+                    imagePath: img.path,
+                    error: error.message
+                });
+                // Continue processing other images even if one fails
+            }
+        }
+
+        logger.info("Completed processing images for stream", {
+            streamId,
+            processed: msgItems.length,
+            pending: stream.pendingImages.length
+        });
+
+        return msgItems;
+    }
+
+    /**
+     * 标记流为完成状态（异步，处理待发送的图片）
+     */
+    async finishStream(streamId) {
         this.startCleanup();
         const stream = this.streams.get(streamId);
         if (!stream) {
@@ -127,12 +221,18 @@ class StreamManager {
             return false;
         }
 
+        // Process pending images before finishing
+        if (stream.pendingImages.length > 0) {
+            stream.msgItem = await this.processPendingImages(streamId);
+        }
+
         stream.finished = true;
         stream.updatedAt = Date.now();
 
         logger.info("Stream finished", {
             streamId,
-            contentLength: stream.content.length
+            contentLength: stream.content.length,
+            imageCount: stream.msgItem.length
         });
 
         return true;