@sunnoy/wecom 1.8.0 → 1.9.0

package/README.md

@@ -9,7 +9,6 @@
 - [前置要求](#前置要求)
 - [安装](#安装)
 - [运行测试](#运行测试)
-- [运行真实 E2E 测试（远程 OpenClaw）](#运行真实-e2e-测试远程-openclaw)
 
 ### 配置与接入
 - [配置](#配置)
@@ -25,6 +24,7 @@
 - [流式回复能力](#流式回复能力)
 - [管理员用户](#管理员用户)
 - [动态 Agent 路由](#动态-agent-路由)
+- [Bindings 路由（多 Agent 绑定）](#bindings-路由多-agent-绑定)
 - [支持的目标格式](#支持的目标格式)
 - [指令白名单](#指令白名单)
 - [消息防抖合并](#消息防抖合并)
@@ -102,46 +102,6 @@ npm test
 
 运行单元测试（使用 Node.js 内置测试运行器）。
 
-### 运行真实 E2E 测试（远程 OpenClaw）
-
-本项目新增了真实联调 e2e 用例（`tests/e2e/remote-wecom.e2e.test.js`），会对真实 `/webhooks/wecom` 做加密请求、验证握手、发送消息并轮询 stream 直到结束。
-
-1. 使用你当前环境的 `ssh ali-ai` 一键执行（自动读取远程 `~/.openclaw/openclaw.json`，并建立本地隧道）：
-
-```bash
-npm run test:e2e:ali-ai
-```
-
-2. 或者手动指定环境变量执行：
-
-```bash
-E2E_WECOM_BASE_URL=http://127.0.0.1:28789 \
-E2E_WECOM_TOKEN=xxx \
-E2E_WECOM_ENCODING_AES_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
-E2E_WECOM_WEBHOOK_PATH=/webhooks/wecom \
-npm run test:e2e
-```
-
-可选变量：
-- `E2E_WECOM_TEST_USER`（默认 `wecom-e2e-user`）
-- `E2E_WECOM_TEST_COMMAND`（默认 `/status`）
-- `E2E_WECOM_POLL_INTERVAL_MS`（默认 `1200`）
-- `E2E_WECOM_STREAM_TIMEOUT_MS`（默认 `90000`）
-- `E2E_WECOM_ENABLE_BROWSER_CASE`（默认 `1`，设置 `0` 可跳过浏览器场景）
-- `E2E_WECOM_BROWSER_TIMEOUT_MS`（默认 `180000`）
-- `E2E_WECOM_BROWSER_REQUIRE_IMAGE`（默认 `0`，设置 `1` 强制断言 `msg_item` 图片出站）
-- `E2E_WECOM_BROWSER_PROMPT`（浏览器场景自定义提示词）
-- `E2E_WECOM_BROWSER_BING_PDF_PROMPT`（Bing + 保存 PDF 场景提示词）
-- `E2E_WECOM_ENABLE_BROWSER_BING_PDF_CASE`（默认 `1`）
-- `E2E_BROWSER_PREPARE_MODE`（`check`/`install`/`off`，默认 `check`）
-- `E2E_BROWSER_REQUIRE_READY`（默认 `0`，设置 `1` 时浏览器环境不满足则中止）
-- `E2E_COLLECT_BROWSER_PDF`（默认 `1`，执行后自动收集远程 sandbox 中的 PDF）
-- `E2E_PDF_OUTPUT_DIR`（默认 `tests/e2e/artifacts`）
-
-> 说明：`test:e2e:ali-ai` 会消耗远程实例的真实 LLM token，并覆盖多种真实入站/出站场景（含浏览器相关场景）。
-> 说明：执行 `test:e2e:ali-ai` 会先做 browser sandbox 准备检查（`prepare-browser-sandbox.sh`），测试后会尝试抓取 PDF 产物（`collect-browser-pdf.sh`）供用户下载。
-> 说明：当 browser sandbox 未就绪（缺浏览器二进制或缺 `browser` skill）时，Bing+PDF case 会自动跳过，并在准备检查输出中标记 `STATUS=MISSING`。
-
 ## 配置
 
 在 OpenClaw 配置文件（`~/.openclaw/openclaw.json`）中添加：
@@ -657,6 +617,49 @@ openclaw agent --agent myagent \
 
 模板目录中的文件会复制到动态 Agent 的工作区（`~/.openclaw/workspace-<agentId>/`），仅当目标文件不存在时才会复制。
 
+## Bindings 路由（多 Agent 绑定）
+
+通过 OpenClaw 的 `bindings` 配置，可以将不同的 WeCom 账户绑定到不同的 Agent，实现多 Agent 精确路由。
+
+### 配置示例
+
+```json
+{
+  "bindings": [
+    {
+      "agentId": "amy",
+      "match": {
+        "channel": "wecom",
+        "accountId": "bot1"
+      }
+    },
+    {
+      "agentId": "bob",
+      "match": {
+        "channel": "wecom",
+        "accountId": "bot2"
+      }
+    }
+  ]
+}
+```
+
+### 工作原理
+
+1. 当消息到达时，插件检查 `bindings` 中是否有匹配当前 `channel: "wecom"` 和 `accountId` 的条目
+2. 如果匹配到 binding，使用 binding 指定的 `agentId` 路由，**不会被动态 Agent 覆盖**
+3. 如果没有匹配的 binding，按正常的动态 Agent 路由逻辑处理
+
+### 与动态 Agent 的关系
+
+| 场景 | 路由结果 |
+|------|---------|
+| 有匹配 binding | 使用 binding 中的 `agentId` |
+| 无 binding + 动态 Agent 开启 | 自动生成 `wecom-dm-<userId>` 等 |
+| 无 binding + 动态 Agent 关闭 | 使用默认 Agent |
+
+> 💡 **典型场景**：多账号模式下，`bot1` 的所有消息路由到 `amy` Agent，`bot2` 的消息路由到 `bob` Agent，各自拥有独立的指令集和上下文。
+
 ## 支持的目标格式
 
 插件支持多种目标格式，用于消息路由和 Webhook 发送：
@@ -944,13 +947,18 @@ openclaw-plugin-wecom/
 │   ├── webhook-targets.js   # Webhook 目标管理
 │   └── workspace-template.js # 工作区模板
 ├── tests/                   # 测试目录
-│   ├── e2e/
-│   │   ├── remote-wecom.e2e.test.js # 真实远程 E2E（加密请求 + stream 轮询）
-│   │   └── run-ali-ai.sh    # ssh ali-ai 一键联调脚本
-│   │   ├── prepare-browser-sandbox.sh # browser sandbox 环境检查/准备
-│   │   └── collect-browser-pdf.sh # 收集并下载 PDF 测试产物
+│   ├── accounts-reserved-keys.test.js # 多账号保留键测试
+│   ├── api-base-url.test.js # API 基础 URL 测试
+│   ├── channel-plugin.media-type.test.js # 媒体类型测试
+│   ├── dynamic-agent.test.js # 动态 Agent 路由测试
+│   ├── http-handler.test.js # HTTP 处理器测试
+│   ├── inbound-processor.image-merge.test.js # 图片合并测试
+│   ├── issue-fixes.test.js  # Issue 修复验证测试
 │   ├── outbound.test.js     # 出站投递回退逻辑测试
+│   ├── outbound-security.test.js # 出站安全测试
 │   ├── target.test.js       # 目标解析器测试
+│   ├── think-parser.test.js # 思考标签解析测试
+│   ├── workspace-template.test.js # 工作区模板测试
 │   └── xml-parser.test.js   # XML 解析器测试
 ├── README.md                # 本文档
 ├── CONTRIBUTING.md          # 贡献指南

package/index.js

@@ -4,45 +4,50 @@ import { wecomChannelPlugin } from "./wecom/channel-plugin.js";
 import { wecomHttpHandler } from "./wecom/http-handler.js";
 import { responseUrls, setOpenclawConfig, setRuntime, streamMeta } from "./wecom/state.js";
 
-// Periodic cleanup for streamMeta and expired responseUrls to prevent memory leaks.
-setInterval(() => {
-  const now = Date.now();
-  // Clean streamMeta entries whose stream no longer exists in streamManager.
-  for (const streamId of streamMeta.keys()) {
-    if (!streamManager.hasStream(streamId)) {
-      streamMeta.delete(streamId);
-    }
-  }
-  // Clean expired responseUrls (older than 1 hour).
-  for (const [key, entry] of responseUrls.entries()) {
-    if (now > entry.expiresAt) {
-      responseUrls.delete(key);
-    }
-  }
-}, 60 * 1000).unref();
+function emptyPluginConfigSchema() {
+  return {
+    safeParse(value) {
+      if (value === undefined) return { success: true, data: undefined };
+      if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { success: false, error: { message: "expected config object" } };
+      }
+      return { success: true, data: value };
+    },
+  };
+}
+
+let cleanupTimer = null;
 
 const plugin = {
-  // Plugin id should match `openclaw.plugin.json` id (and config.plugins.entries key).
   id: "wecom",
   name: "Enterprise WeChat",
   description: "Enterprise WeChat AI Bot channel plugin for OpenClaw",
-  configSchema: { type: "object", additionalProperties: true, properties: {} },
+  configSchema: emptyPluginConfigSchema(),
   register(api) {
     logger.info("WeCom plugin registering...");
 
-    // Save runtime for message processing
     setRuntime(api.runtime);
     setOpenclawConfig(api.config);
 
-    // Register channel
+    if (cleanupTimer) clearInterval(cleanupTimer);
+    cleanupTimer = setInterval(() => {
+      const now = Date.now();
+      for (const streamId of streamMeta.keys()) {
+        if (!streamManager.hasStream(streamId)) {
+          streamMeta.delete(streamId);
+        }
+      }
+      for (const [key, entry] of responseUrls.entries()) {
+        if (now > entry.expiresAt) {
+          responseUrls.delete(key);
+        }
+      }
+    }, 60_000);
+    cleanupTimer.unref();
+
     api.registerChannel({ plugin: wecomChannelPlugin });
     logger.info("WeCom channel registered");
 
-    // Register webhook HTTP route with auth: "plugin" so gateway does NOT
-    // enforce Bearer-token auth. WeCom callbacks use msg_signature verification
-    // which the plugin handles internally.
-    // OpenClaw 3.2 removed registerHttpHandler; use registerHttpRoute with
-    // auth: "plugin" + match: "prefix" to handle all /webhooks/* paths.
     api.registerHttpRoute({
       path: "/webhooks",
       handler: wecomHttpHandler,

package/openclaw.plugin.json

@@ -2,12 +2,12 @@
   "id": "wecom",
   "name": "OpenClaw WeCom",
   "description": "Enterprise WeChat (WeCom) messaging channel plugin for OpenClaw",
-  "channels": [
-    "wecom"
-  ],
   "configSchema": {
     "type": "object",
     "additionalProperties": true,
     "properties": {}
-  }
+  },
+  "channels": [
+    "wecom"
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sunnoy/wecom",
-    "version": "1.8.0",
+    "version": "1.9.0",
     "description": "Enterprise WeChat AI Bot channel plugin for OpenClaw",
     "type": "module",
     "main": "index.js",
@@ -28,9 +28,7 @@
     },
     "scripts": {
         "test": "npm run test:unit",
-        "test:unit": "node --test tests/*.test.js",
-        "test:e2e": "node --test tests/e2e/*.e2e.test.js",
-        "test:e2e:ali-ai": "bash tests/e2e/run-ali-ai.sh"
+        "test:unit": "node --test tests/*.test.js"
     },
     "openclaw": {
         "extensions": [

package/utils.js

@@ -79,6 +79,57 @@ export class MessageDeduplicator {
     this.seen.set(msgId, true);
   }
 }
+// ============================================================================
+// Text chunking for WeCom Agent API (2048-byte limit per message)
+// ============================================================================
+const AGENT_TEXT_BYTE_LIMIT = 2000; // safe margin below 2048
+
+/**
+ * Split a string into chunks that each fit within a byte limit (UTF-8).
+ * Splits at newline boundaries when possible, otherwise at character boundaries.
+ */
+export function splitTextByByteLimit(text, limit = AGENT_TEXT_BYTE_LIMIT) {
+  if (Buffer.byteLength(text, "utf8") <= limit) {
+    return [text];
+  }
+
+  const chunks = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    if (Buffer.byteLength(remaining, "utf8") <= limit) {
+      chunks.push(remaining);
+      break;
+    }
+
+    // Binary search for the max char index that fits within the byte limit.
+    let lo = 0;
+    let hi = remaining.length;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >>> 1;
+      if (Buffer.byteLength(remaining.slice(0, mid), "utf8") <= limit) {
+        lo = mid;
+      } else {
+        hi = mid - 1;
+      }
+    }
+
+    let splitAt = lo;
+
+    // Prefer splitting at a newline boundary within the last 20% of the chunk.
+    const searchStart = Math.max(0, Math.floor(splitAt * 0.8));
+    const lastNewline = remaining.lastIndexOf("\n", splitAt - 1);
+    if (lastNewline >= searchStart) {
+      splitAt = lastNewline + 1;
+    }
+
+    chunks.push(remaining.slice(0, splitAt));
+    remaining = remaining.slice(splitAt);
+  }
+
+  return chunks;
+}
+
 // ============================================================================
 // Constants
 // ============================================================================

package/wecom/agent-inbound.js

@@ -27,6 +27,7 @@ import { resolveAgentMediaTypeFromFilename } from "./channel-plugin.js";
 import { wecomFetch } from "./http.js";
 import { getRuntime, resolveAgentConfig } from "./state.js";
 import { ensureDynamicAgentListed } from "./workspace-template.js";
+import { splitTextByByteLimit } from "../utils.js";
 import {
   extractEncryptFromXml,
   parseXml,
@@ -332,9 +333,19 @@ async function processAgentMessage({
     peer: { kind: peerKind, id: peerId },
   });
 
-  if (targetAgentId) {
+  const hasExplicitBinding = Array.isArray(config?.bindings) &&
+    config.bindings.some((b) =>
+      b.match?.channel === "wecom" && b.match?.accountId === accountId,
+    );
+
+  if (targetAgentId && !hasExplicitBinding) {
     route.agentId = targetAgentId;
     route.sessionKey = `agent:${targetAgentId}:${peerKind}:${peerId}`;
+  } else if (hasExplicitBinding) {
+    logger.debug("[agent-inbound] explicit binding found, skipping dynamic agent override", {
+      accountId,
+      resolvedAgentId: route.agentId,
+    });
   }
 
   // ── Build inbound context ─────────────────────────────────────
@@ -469,15 +480,18 @@ async function processAgentMessage({
           }
         }
 
-        // ── Handle text ────────────────────────────────────────
+        // ── Handle text (with chunking for long messages) ─────
         if (!text.trim()) return;
 
         try {
-          // Agent mode: reply via API to the sender (DM, even for group messages)
-          await agentSendText({ agent: agentConfig, toUser: fromUser, text });
+          const chunks = splitTextByByteLimit(text);
+          for (const chunk of chunks) {
+            await agentSendText({ agent: agentConfig, toUser: fromUser, text: chunk });
+          }
           logger.info("[agent-inbound] reply delivered", {
             kind: info.kind,
             to: fromUser,
+            chunks: chunks.length,
             contentPreview: text.substring(0, 50),
           });
         } catch (err) {

package/wecom/channel-plugin.js

@@ -14,6 +14,7 @@ import { webhookSendImage, webhookSendText, webhookUploadFile, webhookSendFile }
 import { normalizeWebhookPath, registerWebhookTarget } from "./webhook-targets.js";
 import { wecomFetch, setConfigProxyUrl } from "./http.js";
 import { setApiBaseUrl } from "./constants.js";
+import { splitTextByByteLimit } from "../utils.js";
 
 
 const AGENT_IMAGE_EXTS = new Set(["jpg", "jpeg", "png", "gif", "bmp"]);
@@ -46,7 +47,7 @@ export const wecomChannelPlugin = {
     schema: {
       $schema: "http://json-schema.org/draft-07/schema#",
       type: "object",
-      additionalProperties: false,
+      additionalProperties: true,
       properties: {
         enabled: {
           type: "boolean",
@@ -283,6 +284,7 @@ export const wecomChannelPlugin = {
   },
   // Outbound adapter: all replies are streamed for WeCom AI Bot compatibility.
   outbound: {
+    deliveryMode: "direct",
     sendText: async ({ cfg: _cfg, to, text, accountId: _accountId }) => {
       // `to` format: "wecom:userid" or "userid".
       const userId = to.replace(/^wecom:/, "");
@@ -399,10 +401,14 @@ export const wecomChannelPlugin = {
       if (agentConfig) {
         try {
           const agentTarget = (target && !target.webhook) ? target : { toUser: userId };
-          await agentSendText({ agent: agentConfig, ...agentTarget, text });
+          const chunks = splitTextByByteLimit(text);
+          for (const chunk of chunks) {
+            await agentSendText({ agent: agentConfig, ...agentTarget, text: chunk });
+          }
           logger.info("WeCom: sent via Agent API fallback (sendText)", {
             userId,
             to,
+            chunks: chunks.length,
             contentPreview: text.substring(0, 50),
           });
           return {

package/wecom/http-handler.js

@@ -128,6 +128,20 @@ async function handleWecomRequest(req, res, targets, query, path) {
     const body = Buffer.concat(chunks).toString("utf-8");
     logger.debug("WeCom message received", { bodyLength: body.length });
 
+    if (body.trimStart().startsWith("<")) {
+      logger.warn("WeCom: XML body received on Bot webhook (expected JSON). Agent callbacks should use /webhooks/app endpoint.", {
+        path,
+        bodyPreview: body.substring(0, 120),
+      });
+      res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end(
+        "Invalid format: Bot webhook expects JSON.\n" +
+        "If you are configuring a WeCom self-built application (自建应用), " +
+        "use the Agent callback URL: /webhooks/app/{accountId}",
+      );
+      return;
+    }
+
     const webhook = new WecomWebhook({
       token: target.account.token,
       encodingAesKey: target.account.encodingAesKey,

package/wecom/inbound-processor.js

@@ -50,16 +50,15 @@ export function flushMessageBuffer(streamKey, target) {
     const mergedContent = messages.map((m) => m.content || "").filter(Boolean).join("\n");
     primaryMsg.content = mergedContent;
 
-    // Merge image attachments.
-    const allImageUrls = messages.flatMap((m) => m.imageUrls || []);
-    if (allImageUrls.length > 0) {
-      primaryMsg.imageUrls = allImageUrls;
-    }
-    const singleImages = messages.map((m) => m.imageUrl).filter(Boolean);
-    if (singleImages.length > 0 && !primaryMsg.imageUrl) {
-      primaryMsg.imageUrl = singleImages[0];
-      if (singleImages.length > 1) {
-        primaryMsg.imageUrls = [...(primaryMsg.imageUrls || []), ...singleImages.slice(1)];
+    // Merge image attachments from all buffered messages.
+    // Collect single imageUrl fields first, then multi imageUrls arrays.
+    const allSingleImageUrls = messages.map((m) => m.imageUrl).filter(Boolean);
+    const allMultiImageUrls = messages.flatMap((m) => m.imageUrls || []);
+    const mergedImageUrls = [...allSingleImageUrls, ...allMultiImageUrls];
+    if (mergedImageUrls.length > 0) {
+      primaryMsg.imageUrl = mergedImageUrls[0];
+      if (mergedImageUrls.length > 1) {
+        primaryMsg.imageUrls = mergedImageUrls.slice(1);
       }
     }
 
@@ -275,10 +274,21 @@ export async function processInboundMessage({
     },
   });
 
-  // Override default route with deterministic dynamic agent session key.
-  if (targetAgentId) {
+  // Override default route with deterministic dynamic agent session key,
+  // but respect explicit bindings configured for this channel + account.
+  const hasExplicitBinding = Array.isArray(config?.bindings) &&
+    config.bindings.some((b) =>
+      b.match?.channel === "wecom" && b.match?.accountId === account.accountId,
+    );
+
+  if (targetAgentId && !hasExplicitBinding) {
     route.agentId = targetAgentId;
     route.sessionKey = `agent:${targetAgentId}:${peerKind}:${peerId}`;
+  } else if (hasExplicitBinding) {
+    logger.debug("WeCom: explicit binding found, skipping dynamic agent override", {
+      accountId: account.accountId,
+      resolvedAgentId: route.agentId,
+    });
   }
 
   // Build inbound context
@@ -324,7 +334,9 @@ export async function processInboundMessage({
   };
 
   // Download, decrypt, and attach media when present.
-  const allImageUrls = imageUrl ? [imageUrl] : imageUrls;
+  // Combine imageUrl (single) and imageUrls (array) so both are processed
+  // when a merged message carries values in both fields.
+  const allImageUrls = [imageUrl, ...imageUrls].filter(Boolean);
 
   if (allImageUrls.length > 0) {
     const mediaPaths = [];