@sunnoy/wecom 1.0.0

package/client.js

@@ -0,0 +1,127 @@
+/**
+ * WeCom AI Bot Client
+ * 智能机器人专用 - 只使用 response_url 回复，不需要 access_token
+ * https://developer.work.weixin.qq.com/document/path/101039
+ */
+
+import { logger } from "./logger.js";
+import { withRetry, parseWecomError, CONSTANTS } from "./utils.js";
+
+/**
+ * 通过 response_url 主动回复消息
+ * https://developer.work.weixin.qq.com/document/path/101138
+ */
+export async function sendReplyMessage(responseUrl, message) {
+    if (!responseUrl) {
+        throw new Error("response_url is required");
+    }
+
+    logger.debug("Sending reply via response_url", { msgtype: message.msgtype });
+
+    return await withRetry(async () => {
+        const res = await fetch(responseUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(message),
+            signal: AbortSignal.timeout(CONSTANTS.WEBHOOK_RESPONSE_TIMEOUT_MS),
+        });
+
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+        }
+
+        const data = await res.json();
+        if (data.errcode !== 0) {
+            const errorInfo = parseWecomError(data.errcode, data.errmsg);
+            throw new Error(`Response failed: [${data.errcode}] ${errorInfo.message}`);
+        }
+
+        logger.info("Reply sent successfully via response_url");
+        return data;
+    }, {
+        retries: 2,
+        minTimeout: 500,
+        maxTimeout: 2000,
+        onRetry: (error, attempt) => {
+            logger.warn(`Reply retry ${attempt}/2`, { error: error.message });
+        },
+    });
+}
+
+/**
+ * 发送 Markdown 消息
+ */
+export async function sendMarkdownReply(responseUrl, content) {
+    return sendReplyMessage(responseUrl, {
+        msgtype: "markdown",
+        markdown: { content },
+    });
+}
+
+/**
+ * 发送文本消息
+ */
+export async function sendTextReply(responseUrl, content) {
+    return sendReplyMessage(responseUrl, {
+        msgtype: "text",
+        text: { content },
+    });
+}
+
+/**
+ * 发送流式响应片段
+ * https://developer.work.weixin.qq.com/document/path/101031#流式消息回复
+ * 
+ * @param responseUrl - 回调中返回的 response_url
+ * @param streamId - 流ID，同一轮对话保持一致
+ * @param content - 本次消息内容 (markdown 格式)
+ * @param isFinished - 是否结束流式响应
+ */
+export async function sendStreamChunk(responseUrl, streamId, content, isFinished = false) {
+    if (!responseUrl) {
+        throw new Error("response_url is required for streaming");
+    }
+
+    const message = {
+        msgtype: "stream",
+        stream: {
+            id: streamId,
+            finish: isFinished,
+            content: content,
+            // msg_item: [], // 可选：图片等
+            // feedback: { id: "feedid" } // 可选：反馈ID
+        },
+    };
+
+    logger.debug("Sending stream chunk", { streamId, isFinished, length: content.length });
+
+    const res = await fetch(responseUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(message),
+        signal: AbortSignal.timeout(CONSTANTS.WEBHOOK_RESPONSE_TIMEOUT_MS),
+    });
+
+    if (!res.ok) {
+        throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+    }
+
+    const data = await res.json();
+    if (data.errcode !== 0) {
+        const errorInfo = parseWecomError(data.errcode, data.errmsg);
+        throw new Error(`Stream response failed: [${data.errcode}] ${errorInfo.message}`);
+    }
+
+    return data;
+}
+
+/**
+ * 发送模板卡片消息
+ * https://developer.work.weixin.qq.com/document/path/101061
+ */
+export async function sendTemplateCardReply(responseUrl, card) {
+    return sendReplyMessage(responseUrl, {
+        msgtype: "template_card",
+        template_card: card,
+    });
+}

package/crypto.js

@@ -0,0 +1,108 @@
+import { createCipheriv, createDecipheriv, randomBytes, createHash } from "node:crypto";
+import { XMLParser, XMLBuilder } from "fast-xml-parser";
+import { CONSTANTS } from "./utils.js";
+import { logger } from "./logger.js";
+
+/**
+ * Enterprise WeChat Intelligent Robot Crypto Implementation
+ * Simplified for AI Bot mode (no corpId validation)
+ */
+export class WecomCrypto {
+    token;
+    encodingAesKey;
+    aesKey;
+    iv;
+
+    constructor(token, encodingAesKey) {
+        if (!encodingAesKey || encodingAesKey.length !== CONSTANTS.AES_KEY_LENGTH) {
+            throw new Error(`EncodingAESKey invalid: length must be ${CONSTANTS.AES_KEY_LENGTH}`);
+        }
+        if (!token) {
+            throw new Error("Token is required");
+        }
+        this.token = token;
+        this.encodingAesKey = encodingAesKey;
+        this.aesKey = Buffer.from(encodingAesKey + "=", "base64");
+        this.iv = this.aesKey.subarray(0, 16);
+        logger.debug("WecomCrypto initialized (AI Bot mode)");
+    }
+
+    getSignature(timestamp, nonce, encrypt) {
+        const shasum = createHash("sha1");
+        const arr = [this.token, timestamp, nonce, encrypt].sort();
+        shasum.update(arr.join(""));
+        return shasum.digest("hex");
+    }
+
+    decrypt(text) {
+        let decipher;
+        try {
+            decipher = createDecipheriv("aes-256-cbc", this.aesKey, this.iv);
+            decipher.setAutoPadding(false);
+        } catch (e) {
+            throw new Error(`Decrypt init failed: ${String(e)}`);
+        }
+
+        let deciphered = Buffer.concat([
+            decipher.update(text, "base64"),
+            decipher.final(),
+        ]);
+
+        deciphered = this.decodePkcs7(deciphered);
+
+        // Format: 16 random bytes | 4 bytes msg_len | msg_content | appid
+        const content = deciphered.subarray(16);
+        const lenList = content.subarray(0, 4);
+        const xmlLen = lenList.readUInt32BE(0);
+        const xmlContent = content.subarray(4, 4 + xmlLen).toString("utf-8");
+        // For AI Bot mode, corpId/appid is empty, skip validation
+
+        return { message: xmlContent };
+    }
+
+    encrypt(text) {
+        // For AI Bot mode, corpId is empty
+        const random16 = randomBytes(16);
+        const msgBuffer = Buffer.from(text);
+        const lenBuffer = Buffer.alloc(4);
+        lenBuffer.writeUInt32BE(msgBuffer.length, 0);
+
+        const rawMsg = Buffer.concat([random16, lenBuffer, msgBuffer]);
+        const encoded = this.encodePkcs7(rawMsg);
+
+        const cipher = createCipheriv("aes-256-cbc", this.aesKey, this.iv);
+        cipher.setAutoPadding(false);
+        const ciphered = Buffer.concat([cipher.update(encoded), cipher.final()]);
+        return ciphered.toString("base64");
+    }
+
+    encodePkcs7(buff) {
+        const blockSize = CONSTANTS.AES_BLOCK_SIZE;
+        const amountToPad = blockSize - (buff.length % blockSize);
+        const pad = Buffer.alloc(amountToPad, amountToPad);
+        return Buffer.concat([buff, pad]);
+    }
+
+    decodePkcs7(buff) {
+        const pad = buff[buff.length - 1];
+        if (pad < 1 || pad > CONSTANTS.AES_BLOCK_SIZE) {
+            throw new Error(`Invalid PKCS7 padding: ${pad}`);
+        }
+        for (let i = buff.length - pad; i < buff.length; i++) {
+            if (buff[i] !== pad) {
+                throw new Error("Invalid PKCS7 padding: inconsistent padding bytes");
+            }
+        }
+        return buff.subarray(0, buff.length - pad);
+    }
+}
+
+export const xmlParser = new XMLParser({
+    ignoreAttributes: true,
+    parseTagValue: false
+});
+
+export const xmlBuilder = new XMLBuilder({
+    format: false,
+    ignoreAttributes: true
+});

package/dynamic-agent.js

@@ -0,0 +1,120 @@
+import { logger } from "./logger.js";
+
+/**
+ * Dynamic Agent Manager (Minimal Version)
+ * 
+ * 极简版：插件只负责生成 AgentId
+ * 所有 Workspace 创建和 Bootstrap 文件由 OpenClaw 主程序自动处理
+ * 
+ * 流程：
+ * 1. 插件收到消息 → generateAgentId() 生成 agentId
+ * 2. 插件构造 SessionKey → `agent:{agentId}:{peerKind}:{peerId}`
+ * 3. OpenClaw 解析 SessionKey → 提取 agentId
+ * 4. OpenClaw 调用 resolveAgentWorkspaceDir() → fallback 到 ~/.openclaw/workspace-{agentId}
+ * 5. OpenClaw 调用 ensureAgentWorkspace() → 自动创建目录和 Bootstrap 文件
+ */
+
+/**
+ * 生成 AgentId
+ * 规范：wecom-dm-{userId} 或 wecom-group-{groupId}
+ * 
+ * @param {string} chatType - "dm" 或 "group"
+ * @param {string} peerId - userId 或 groupId
+ * @returns {string} agentId
+ */
+export function generateAgentId(chatType, peerId) {
+    const sanitizedId = String(peerId).toLowerCase().replace(/[^a-z0-9_-]/g, "_");
+    if (chatType === "group") {
+        return `wecom-group-${sanitizedId}`;
+    }
+    return `wecom-dm-${sanitizedId}`;
+}
+
+/**
+ * 获取动态 Agent 配置
+ */
+export function getDynamicAgentConfig(config) {
+    const wecom = config?.channels?.wecom || {};
+    return {
+        enabled: wecom.dynamicAgents?.enabled !== false,
+
+        // 私聊配置
+        dmCreateAgent: wecom.dm?.createAgentOnFirstMessage !== false,
+
+        // 群聊配置
+        groupEnabled: wecom.groupChat?.enabled !== false,
+        groupRequireMention: wecom.groupChat?.requireMention !== false,
+        groupMentionPatterns: wecom.groupChat?.mentionPatterns || ["@"],
+        groupCreateAgent: wecom.groupChat?.createAgentOnFirstMessage !== false,
+        groupHistoryLimit: wecom.groupChat?.historyLimit || 10,
+    };
+}
+
+/**
+ * 检查是否应该为此消息创建/使用动态 Agent
+ * 
+ * @param {Object} options
+ * @param {string} options.chatType - "dm" 或 "group"
+ * @param {Object} options.config - openclaw 配置
+ * @returns {boolean}
+ */
+export function shouldUseDynamicAgent({ chatType, config }) {
+    const dynamicConfig = getDynamicAgentConfig(config);
+
+    if (!dynamicConfig.enabled) {
+        return false;
+    }
+
+    if (chatType === "dm") {
+        return dynamicConfig.dmCreateAgent;
+    }
+
+    if (chatType === "group") {
+        return dynamicConfig.groupCreateAgent;
+    }
+
+    return false;
+}
+
+/**
+ * 检查群聊消息是否满足触发条件（@提及）
+ */
+export function shouldTriggerGroupResponse(content, config) {
+    const dynamicConfig = getDynamicAgentConfig(config);
+
+    if (!dynamicConfig.groupEnabled) {
+        return false;
+    }
+
+    if (!dynamicConfig.groupRequireMention) {
+        return true; // 不需要 @，所有消息都触发
+    }
+
+    // 检查是否包含 @提及
+    const patterns = dynamicConfig.groupMentionPatterns;
+    for (const pattern of patterns) {
+        if (content.includes(pattern)) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * 从群聊消息中提取实际内容（移除 @提及）
+ */
+export function extractGroupMessageContent(content, config) {
+    const dynamicConfig = getDynamicAgentConfig(config);
+    let cleanContent = content;
+
+    // 移除 @提及 pattern
+    const patterns = dynamicConfig.groupMentionPatterns;
+    for (const pattern of patterns) {
+        // 移除 @xxx 格式的提及（包括后面可能的空格）
+        const regex = new RegExp(`${pattern}\\S*\\s*`, "g");
+        cleanContent = cleanContent.replace(regex, "");
+    }
+
+    return cleanContent.trim();
+}

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;
+    }
+}