openclaw-plugin-wecom 0.2.5 → 0.3.0

package/README.md

@@ -7,18 +7,65 @@
 ## ✨ Key Features
 
 - 🌊 **Streaming Output**: Based on the latest WeCom AI Bot streaming mechanism for a smooth typing-like response experience.
-- 🤖 **Dynamic Agent Management**: Automatically creates independent Agent instances for each direct message user and group chat. Each instance has its own workspace, configurations, and conversation history, ensuring data isolation and security.
+- 🤖 **Dynamic Agent Management**: Automatically creates an independent Agent per DM user and per group chat. Each Agent has its own workspace and conversation history, keeping data isolated by default.
 - 👥 **Deep Group Chat Integration**: Supports group message parsing and precise triggering via @mentions.
 - 🛠️ **Enhanced Commands**: Built-in support for common commands (e.g., `/new` for a new session, `/status` to check status) with command allowlist configuration.
 - 🔒 **Security & Authentication**: Full support for WeCom message encryption/decryption, URL verification, and sender identity validation.
 - ⚡ **High-Performance Async Processing**: Uses an asynchronous message processing architecture to ensure high responsiveness of the WeCom gateway even during long-running AI inference.
 
+## 🤖 Dynamic Agent Routing (How it works)
+
+OpenClaw decides which Agent to run by parsing `SessionKey`. This plugin uses that mechanism to provide per-user / per-group isolation:
+
+1. When a WeCom message arrives, the plugin generates a deterministic `agentId`:
+   - DM: `wxwork-dm-<userId>`
+   - Group: `wxwork-group-<chatId>`
+2. The plugin routes the message by setting `SessionKey` to:
+   - `agent:<agentId>:<peerKind>:<peerId>`
+3. OpenClaw extracts `<agentId>` from `SessionKey` and will automatically create / reuse the Agent workspace (typically under `~/.openclaw/workspace-<agentId>` for non-default agents).
+
+### Multi-tenant by design
+
+Dynamic agents act like lightweight “tenants”:
+
+- **Per-user / per-group isolation**: each DM user or group chat maps to a dedicated Agent with its own workspace and session store keys.
+- **No extra infra**: no database or tenant registry needed — routing is derived deterministically from the inbound identity.
+
+### Dynamic agent config (local config keys)
+
+All keys live under `channels.wxwork`:
+
+- `dynamicAgents.enabled` (boolean, default: `true`): enable/disable per-user/per-group agents.
+- `dm.createAgentOnFirstMessage` (boolean, default: `true`): whether DMs should use dynamic agents.
+- `groupChat.enabled` (boolean, default: `true`): enable group chat handling.
+- `groupChat.createAgentOnFirstMessage` (boolean, default: `true`): whether group chats should use dynamic agents.
+- `groupChat.requireMention` (boolean, default: `true`): require an @mention to respond in groups.
+- `groupChat.mentionPatterns` (string[], default: `["@"]`): patterns treated as “mention”.
+
+If you prefer all WeCom messages to use OpenClaw’s **default Agent**, disable dynamic agents:
+
+```json
+{
+  "channels": {
+    "wxwork": {
+      "dynamicAgents": { "enabled": false }
+    }
+  }
+}
+```
+
 ## 🚀 Quick Start
 
 ### 1. Install Plugin
 
 Run the following in your OpenClaw project directory:
 
+```bash
+openclaw plugins install openclaw-plugin-wecom
+```
+
+Alternatively (if you're managing plugins via `package.json` yourself):
+
 ```bash
 npm install openclaw-plugin-wecom
 ```
@@ -29,6 +76,11 @@ Add the plugin configuration to your OpenClaw configuration file (e.g., `config.
 
 ```json
 {
+  "plugins": {
+    "entries": {
+      "openclaw-plugin-wecom": { "enabled": true }
+    }
+  },
   "channels": {
     "wxwork": {
       "enabled": true,
@@ -44,9 +96,8 @@ Add the plugin configuration to your OpenClaw configuration file (e.g., `config.
         "enabled": true,
         "allowlist": ["/new", "/status", "/help", "/compact"]
       },
-      "dynamicAgent": {
-        "enabled": true,
-        "prefix": "wxwork-"
+      "dynamicAgents": {
+        "enabled": true
       }
     }
   }

package/README_ZH.md

@@ -7,18 +7,65 @@
 ## ✨ 核心特性
 
 - 🌊 **流式输出 (Streaming)**: 基于企业微信最新的 AI 机器人流式分片机制，实现流畅的打字机式回复体验。
-- 🤖 **动态 Agent 管理**: 自动为每位私聊用户和每个群聊创建独立的 Agent 实例。每个实例拥有独立的文件工作区、配置环境和对话上下文，确保数据隔离与安全。
+- 🤖 **动态 Agent 管理**: 默认按“每个私聊用户 / 每个群聊”自动创建独立 Agent。每个 Agent 拥有独立的工作区与对话上下文，实现更强的数据隔离。
 - 👥 **群聊深度集成**: 支持群聊消息解析，可通过 @提及（At-mention）精准触发机器人响应。
 - 🛠️ **指令增强**: 内置常用指令支持（如 `/new` 开启新会话、`/status` 查看状态等），并提供指令白名单配置功能。
 - 🔒 **安全与认证**: 完整支持企业微信消息加解密、URL 验证及发送者身份校验。
 - ⚡ **高性能异步处理**: 采用异步消息处理架构，确保即使在长耗时 AI 推理过程中，企业微信网关也能保持高响应性。
 
+## 🤖 动态 Agent 路由（工作原理）
+
+OpenClaw 会通过解析 `SessionKey` 来决定本次消息由哪个 Agent 处理。本插件利用这一机制实现“按人/按群隔离”：
+
+1. 企业微信消息到达后，插件会生成一个确定性的 `agentId`：
+   - 私聊：`wxwork-dm-<userId>`
+   - 群聊：`wxwork-group-<chatId>`
+2. 插件将消息路由到该 Agent：把 `SessionKey` 设为
+   - `agent:<agentId>:<peerKind>:<peerId>`
+3. OpenClaw 从 `SessionKey` 中提取 `<agentId>`，并自动创建/复用对应的 Agent 工作区（非默认 Agent 通常落在 `~/.openclaw/workspace-<agentId>`）。
+
+### 多租户（按人/按群隔离）亮点
+
+动态 Agent 可以理解为“轻量多租户”实现：
+
+- **按用户/按群聊隔离**：每个私聊用户、每个群聊都映射到独立 Agent，拥有独立 workspace 与会话存储 key。
+- **无需额外基础设施**：不需要租户表/数据库；路由完全由消息身份确定性推导得到。
+
+### 动态 Agent 配置（本地配置项）
+
+配置都在 `channels.wxwork` 下：
+
+- `dynamicAgents.enabled`（boolean，默认：`true`）：是否启用按人/按群动态 Agent。
+- `dm.createAgentOnFirstMessage`（boolean，默认：`true`）：私聊是否使用动态 Agent。
+- `groupChat.enabled`（boolean，默认：`true`）：是否启用群聊处理。
+- `groupChat.createAgentOnFirstMessage`（boolean，默认：`true`）：群聊是否使用动态 Agent。
+- `groupChat.requireMention`（boolean，默认：`true`）：群聊是否必须 @ 提及才响应。
+- `groupChat.mentionPatterns`（string[]，默认：`["@"]`）：哪些字符串算作“提及”。
+
+如果你希望企业微信消息全部进入 OpenClaw 的**默认 Agent**，可以关闭动态 Agent：
+
+```json
+{
+  "channels": {
+    "wxwork": {
+      "dynamicAgents": { "enabled": false }
+    }
+  }
+}
+```
+
 ## 🚀 快速开始
 
 ### 1. 安装插件
 
 在你的 OpenClaw 项目目录中运行：
 
+```bash
+openclaw plugins install openclaw-plugin-wecom
+```
+
+或者（如果你习惯自己在 `package.json` 中管理依赖）：
+
 ```bash
 npm install openclaw-plugin-wecom
 ```
@@ -29,6 +76,11 @@ npm install openclaw-plugin-wecom
 
 ```json
 {
+  "plugins": {
+    "entries": {
+      "openclaw-plugin-wecom": { "enabled": true }
+    }
+  },
   "channels": {
     "wxwork": {
       "enabled": true,
@@ -44,9 +96,8 @@ npm install openclaw-plugin-wecom
         "enabled": true,
         "allowlist": ["/new", "/status", "/help", "/compact"]
       },
-      "dynamicAgent": {
-        "enabled": true,
-        "prefix": "wxwork-"
+      "dynamicAgents": {
+        "enabled": true
       }
     }
   }

package/client.js

@@ -125,15 +125,3 @@ export async function sendTemplateCardReply(responseUrl, 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/dynamic-agent.js

@@ -118,36 +118,3 @@ export function extractGroupMessageContent(content, config) {
 
     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
-}

package/index.js

@@ -807,10 +807,10 @@ async function deliverWxWorkReply({ payload, account, responseUrl, senderId, str
 // =============================================================================
 
 const plugin = {
-  id: "wxwork",
+  id: "openclaw-plugin-wecom",
   name: "Enterprise WeChat",
   description: "Enterprise WeChat AI Bot channel plugin for OpenClaw",
-  configSchema: { type: "object", additionalProperties: true, properties: {} },
+  configSchema: { type: "object", additionalProperties: false, properties: {} },
   register(api) {
     logger.info("WxWork plugin registering...");
 

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "openclaw-plugin-wecom",
+  "name": "OpenClaw WeCom (WxWork)",
+  "description": "Enterprise WeChat (WeCom/WxWork) messaging channel plugin for OpenClaw",
+  "channels": ["wxwork"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -1,13 +1,12 @@
 {
     "name": "openclaw-plugin-wecom",
-    "version": "0.2.5",
+    "version": "0.3.0",
     "description": "Enterprise WeChat AI Bot channel plugin for OpenClaw",
     "type": "module",
     "main": "index.js",
     "files": [
         "index.js",
         "client.js",
-        "config.js",
         "crypto.js",
         "dynamic-agent.js",
         "logger.js",
@@ -16,9 +15,9 @@
         "LICENSE",
         "CONTRIBUTING.md",
         "stream-manager.js",
-        "types.js",
         "utils.js",
-        "webhook.js"
+        "webhook.js",
+        "openclaw.plugin.json"
     ],
     "dependencies": {
         "fast-xml-parser": "^4.2.0"
@@ -31,8 +30,10 @@
             "id": "wxwork",
             "label": "Enterprise WeChat",
             "selectionLabel": "Enterprise WeChat (AI Bot)",
-            "docsPath": "https://github.com/sunnoy/openclaw-plugin-wecom",
+            "docsPath": "/channels/wxwork",
+            "docsLabel": "wxwork",
             "blurb": "Support for Enterprise WeChat (WeCom) AI Bot integration",
+            "order": 90,
             "aliases": [
                 "wecom",
                 "wework"

package/stream-manager.js

@@ -8,9 +8,23 @@ class StreamManager {
     constructor() {
         // streamId -> { content: string, finished: boolean, updatedAt: number, feedbackId: string|null, msgItem: Array }
         this.streams = new Map();
+        this._cleanupInterval = null;
+    }
+
+    /**
+     * 启动定时清理（避免在 import 时产生常驻 side-effect）
+     */
+    startCleanup() {
+        if (this._cleanupInterval) return;
+        this._cleanupInterval = setInterval(() => this.cleanup(), 60 * 1000);
+        // 不阻止进程退出（例如 npm pack / import smoke test）
+        this._cleanupInterval.unref?.();
+    }
 
-        // 自动清理过期的流 (10分钟未更新)
-        setInterval(() => this.cleanup(), 60 * 1000);
+    stopCleanup() {
+        if (!this._cleanupInterval) return;
+        clearInterval(this._cleanupInterval);
+        this._cleanupInterval = null;
     }
 
     /**
@@ -20,6 +34,7 @@ class StreamManager {
      * @param {string} options.feedbackId - 反馈追踪ID (最长256字节)
      */
     createStream(streamId, options = {}) {
+        this.startCleanup();
         logger.debug("Creating stream", { streamId, feedbackId: options.feedbackId });
         this.streams.set(streamId, {
             content: "",
@@ -40,6 +55,7 @@ class StreamManager {
      * @param {Array} options.msgItem - 图文混排列表 (仅finish=true时有效)
      */
     updateStream(streamId, content, finished = false, options = {}) {
+        this.startCleanup();
         const stream = this.streams.get(streamId);
         if (!stream) {
             logger.warn("Stream not found for update", { streamId });
@@ -81,6 +97,7 @@ class StreamManager {
      * 追加内容到流 (用于流式生成)
      */
     appendStream(streamId, chunk) {
+        this.startCleanup();
         const stream = this.streams.get(streamId);
         if (!stream) {
             logger.warn("Stream not found for append", { streamId });
@@ -103,6 +120,7 @@ class StreamManager {
      * 标记流为完成状态
      */
     finishStream(streamId) {
+        this.startCleanup();
         const stream = this.streams.get(streamId);
         if (!stream) {
             logger.warn("Stream not found for finish", { streamId });

package/config.js

@@ -1,11 +0,0 @@
-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/types.js

@@ -1,5 +0,0 @@
-/**
- * Enterprise WeChat (WxWork) Type Definitions
- */
-export {};
-//# sourceMappingURL=types.js.map