openclaw-plugin-wecom 0.2.1

package/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# 贡献指南
+
+感谢你对 OpenClaw 企业微信插件项目的关注！我们欢迎任何形式的贡献，包括修复 bug、改进文档、增加新功能或提出建议。
+
+## 如何贡献
+
+1. **Fork** 本仓库。
+2. **创建特性分支**: `git checkout -b feature/amazing-feature`
+3. **提交你的更改**: `git commit -m 'Add some amazing feature'`
+4. **推送到分支**: `git push origin feature/amazing-feature`
+5. **提交 Pull Request**。
+
+## 提交规范
+
+- 请确保代码风格与项目现有风格保持一致。
+- 提交信息请尽可能简明扼要，说明更改的原因。
+- 如果你的更改涉及功能变更，请同步更新 `README.md`。
+
+## 问题反馈
+
+如果你在使用过程中遇到任何问题，请通过项目的 **Issues** 页面进行反馈，并提供尽可能详细的复现步骤。
+
+## 行为准则
+
+在参与本项目开发的过程中，请保持友善和相互尊重。

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License (ISC)
+
+Copyright (c) 2026
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# OpenClaw 企业微信 (WeCom) AI 机器人插件
+
+`openclaw-plugin-wecom` 是一个专为 [OpenClaw](https://github.com/sunnoy/openclaw-plugin-wecom) 框架开发的企业微信（WeCom）集成插件。它允许你将强大的 AI 能力无缝接入企业微信，并支持多项高级功能。
+
+## ✨ 核心特性
+
+- 🌊 **流式输出 (Streaming)**: 基于企业微信最新的 AI 机器人流式分片机制，实现流畅的打字机式回复体验。
+- 🤖 **动态 Agent 管理**: 自动为每位私聊用户和每个群聊创建独立的 Agent 实例。每个实例拥有独立的文件工作区、配置环境和对话上下文，确保数据隔离与安全。
+- 👥 **群聊深度集成**: 支持群聊消息解析，可通过 @提及（At-mention）精准触发机器人响应。
+- 🛠️ **指令增强**: 内置常用指令支持（如 `/new` 开启新会话、`/status` 查看状态等），并提供指令白名单配置功能。
+- 🔒 **安全与认证**: 完整支持企业微信消息加解密、URL 验证及发送者身份校验。
+- ⚡ **高性能异步处理**: 采用异步消息处理架构，确保即使在长耗时 AI 推理过程中，企业微信网关也能保持高响应性。
+
+## 🚀 快速开始
+
+### 1. 安装插件
+
+在你的 OpenClaw 项目目录中运行：
+
+```bash
+npm install openclaw-plugin-wecom
+```
+
+### 2. 配置插件
+
+在 OpenClaw 的配置文件（如 `config.json`）中添加插件配置：
+
+```json
+{
+  "channels": {
+    "wxwork": {
+      "enabled": true,
+      "token": "你的 Token",
+      "encodingAesKey": "你的 EncodingAESKey",
+      "webhookPath": "/webhooks/wxwork",
+      "accounts": {
+        "default": {
+          "allowFrom": ["*"]
+        }
+      },
+      "commands": {
+        "enabled": true,
+        "allowlist": ["/new", "/status", "/help", "/compact"]
+      },
+      "dynamicAgent": {
+        "enabled": true,
+        "prefix": "wxwork-"
+      }
+    }
+  }
+}
+```
+
+### 3. 企业微信后台设置
+
+1. 在企业微信管理后台创建一个“智能机器人”。
+2. 将机器人的“接收消息配置”中的 URL 设置为你的服务地址（例如：`https://your-domain.com/webhooks/wxwork`）。
+3. 填入对应的 Token 和 EncodingAESKey。
+
+## 🛠️ 指令支持
+
+插件内置了对以下指令的处理：
+
+- `/new`: 重置当前对话，开启全新会话。
+- `/compact`: 压缩当前会话上下文，保留关键摘要以节省 Token。
+- `/help`: 查看帮助信息。
+- `/status`: 查看当前 Agent 及插件状态。
+
+## 📂 项目结构
+
+- `index.js`: 插件入口，处理所有核心路由与生命周期管理。
+- `webhook.js`: 处理企业微信 HTTP 通信、加解密及消息解析。
+- `dynamic-agent.js`: 动态 Agent 分配逻辑。
+- `stream-manager.js`: 管理流式回复的状态与数据分片。
+- `crypto.js`: 企业微信加密算法实现。
+
+## 🤝 贡献规范
+
+我们非常欢迎开发者参与贡献！如果你发现了 Bug 或有更好的功能建议，请提交 Issue 或 Pull Request。
+
+## 📄 开源协议
+
+本项目采用 [ISC License](./LICENSE) 协议。

package/client.js

@@ -0,0 +1,139 @@
+/**
+ * WxWork AI Bot Client
+ * 智能机器人专用 - 只使用 response_url 回复，不需要 access_token
+ * https://developer.work.weixin.qq.com/document/path/101039
+ */
+
+import { logger } from "./logger.js";
+import { withRetry, parseWxWorkError, 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 = parseWxWorkError(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 = parseWxWorkError(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,
+    });
+}
+
+// 兼容旧代码 - 保留 WxWorkClient 类名但简化实现
+export class WxWorkClient {
+    constructor(config) {
+        logger.warn("WxWorkClient is deprecated for AI Bot, use sendReplyMessage directly");
+    }
+
+    // 保留兼容方法
+    async sendStreamResponse(responseUrl, message) {
+        return sendReplyMessage(responseUrl, message);
+    }
+}

package/config.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+export const WxWorkConfigSchema = z.object({
+    enabled: z.boolean().default(false),
+    corpId: z.string().describe("Enterprise ID (CorpID)"),
+    agentId: z.string().describe("Agent ID (Application ID)"),
+    secret: z.string().describe("Application Secret"),
+    token: z.string().describe("Webhook Token"),
+    encodingAesKey: z.string().describe("Webhook EncodingAESKey"),
+    webhookPath: z.string().default("/webhooks/wxwork").describe("Webhook URL path"),
+});
+//# sourceMappingURL=config.js.map

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 WxWorkCrypto {
+    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("WxWorkCrypto 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,153 @@
+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
+ * 规范：wxwork-dm-{userId} 或 wxwork-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 `wxwork-group-${sanitizedId}`;
+    }
+    return `wxwork-dm-${sanitizedId}`;
+}
+
+/**
+ * 获取动态 Agent 配置
+ */
+export function getDynamicAgentConfig(config) {
+    const wxwork = config?.channels?.wxwork || {};
+    return {
+        enabled: wxwork.dynamicAgents?.enabled !== false,
+
+        // 私聊配置
+        dmCreateAgent: wxwork.dm?.createAgentOnFirstMessage !== false,
+
+        // 群聊配置
+        groupEnabled: wxwork.groupChat?.enabled !== false,
+        groupRequireMention: wxwork.groupChat?.requireMention !== false,
+        groupMentionPatterns: wxwork.groupChat?.mentionPatterns || ["@"],
+        groupCreateAgent: wxwork.groupChat?.createAgentOnFirstMessage !== false,
+        groupHistoryLimit: wxwork.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();
+}
+
+// ============ 兼容性导出 ============
+
+/**
+ * @deprecated 不再需要，OpenClaw 会自动创建
+ */
+export async function createDynamicAgent({ chatType, peerId, config }) {
+    const agentId = generateAgentId(chatType, peerId);
+    logger.debug("createDynamicAgent called (no-op, OpenClaw handles creation)", { agentId });
+    return { success: true, agentId, error: null };
+}
+
+/**
+ * @deprecated 不再需要
+ */
+export function ensureDynamicAgent({ chatType, peerId, config }) {
+    const agentId = generateAgentId(chatType, peerId);
+    return { success: true, agentId, isNew: false };
+}
+
+/**
+ * @deprecated 不再需要，OpenClaw 自动处理
+ */
+export function agentExists(config, agentId) {
+    return true; // 总是返回 true，让 OpenClaw 处理
+}
+
+/**
+ * @deprecated 不再需要
+ */
+export function clearAgentCache(agentId) {
+    // no-op
+}