@yanhaidao/wecom 2.2.5 → 2.2.28

package/compat-single-account.md

@@ -0,0 +1,118 @@
+# 附录 A：WeCom 单账号兼容模式配置指南
+
+> 本文档用于历史部署或小规模场景。  
+> 新项目默认推荐多账号矩阵配置（`accounts + bindings.match.accountId`）。
+
+## A.1 适用场景
+
+- 已在线运行单账号配置，短期内不希望迁移。
+- 只有一个 Bot / Agent，不需要账号隔离。
+- 本地 PoC 或临时验证链路。
+
+## A.2 快速配置
+
+### A.2.1 仅 Bot（单智能体）
+
+```bash
+openclaw config set channels.wecom.enabled true
+openclaw config set channels.wecom.bot.token "YOUR_BOT_TOKEN"
+openclaw config set channels.wecom.bot.encodingAESKey "YOUR_BOT_AES_KEY"
+openclaw config set channels.wecom.bot.receiveId ""
+openclaw config set channels.wecom.bot.streamPlaceholderContent "正在思考..."
+openclaw config set channels.wecom.bot.welcomeText "你好！我是 AI 助手"
+
+# DM 门禁（推荐显式设置 policy）
+openclaw config set channels.wecom.bot.dm.policy "open"
+openclaw config set channels.wecom.bot.dm.allowFrom '["*"]'
+```
+
+### A.2.2 增加 Agent 兜底（可选）
+
+```bash
+openclaw config set channels.wecom.agent.corpId "YOUR_CORP_ID"
+openclaw config set channels.wecom.agent.corpSecret "YOUR_CORP_SECRET"
+openclaw config set channels.wecom.agent.agentId 1000001
+openclaw config set channels.wecom.agent.token "YOUR_CALLBACK_TOKEN"
+openclaw config set channels.wecom.agent.encodingAESKey "YOUR_CALLBACK_AES_KEY"
+openclaw config set channels.wecom.agent.welcomeText "欢迎使用智能助手"
+openclaw config set channels.wecom.agent.dm.policy "open"
+openclaw config set channels.wecom.agent.dm.allowFrom '["*"]'
+```
+
+### A.2.3 验证
+
+```bash
+openclaw gateway restart
+openclaw channels status
+```
+
+## A.3 完整单账号配置结构
+
+```jsonc
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+
+      "bot": {
+        "aibotid": "BOT_ID_OPTIONAL",
+        "token": "YOUR_BOT_TOKEN",
+        "encodingAESKey": "YOUR_BOT_AES_KEY",
+        "botIds": ["BOT_ID_OPTIONAL"],
+        "receiveId": "",
+        "streamPlaceholderContent": "正在思考...",
+        "welcomeText": "你好！我是 AI 助手",
+        "dm": {
+          "policy": "open",
+          "allowFrom": ["*"]
+        }
+      },
+
+      "agent": {
+        "corpId": "YOUR_CORP_ID",
+        "corpSecret": "YOUR_CORP_SECRET",
+        "agentId": 1000001,
+        "token": "YOUR_CALLBACK_TOKEN",
+        "encodingAESKey": "YOUR_CALLBACK_AES_KEY",
+        "welcomeText": "欢迎使用智能助手",
+        "dm": {
+          "policy": "open",
+          "allowFrom": ["*"]
+        }
+      },
+
+      "media": {
+        "tempDir": "/tmp/openclaw-wecom-media",
+        "retentionHours": 24,
+        "cleanupOnStart": true,
+        "maxBytes": 26214400
+      },
+
+      "network": {
+        "timeoutMs": 15000,
+        "retries": 2,
+        "retryDelayMs": 500,
+        "egressProxyUrl": "http://proxy.company.local:3128"
+      },
+
+      "dynamicAgents": {
+        "enabled": false,
+        "dmCreateAgent": false,
+        "groupEnabled": false,
+        "adminUsers": []
+      }
+    }
+  }
+}
+```
+
+## A.4 Webhook 路径
+
+- Bot: `/wecom/bot`
+- Agent: `/wecom/agent`
+
+## A.5 迁移建议
+
+如果后续需要多 Bot / 多 Agent 隔离，建议迁移到多账号矩阵模式：
+- 在 `channels.wecom.accounts.<accountId>` 下拆分配置
+- 通过 `bindings[].match.accountId` 映射到对应 OpenClaw agent

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.2.5",
+  "version": "2.2.28",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YanHaidao/wecom.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "ISC",
   "author": "YanHaidao (VX: YanHaidao)",
   "openclaw": {
     "extensions": [
@@ -37,10 +45,10 @@
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.1.26"
+    "openclaw": ">=2026.2.24"
   },
   "devDependencies": {
     "@types/node": "^25.2.0",
     "typescript": "^5.9.3"
   }
-}
+}

package/src/accounts.ts

@@ -1,72 +1,34 @@
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk";
-
-import type { ResolvedWecomAccount, WecomAccountConfig, WecomConfig } from "./types.js";
-
-function listConfiguredAccountIds(cfg: OpenClawConfig): string[] {
-  const accounts = (cfg.channels?.wecom as WecomConfig | undefined)?.accounts;
-  if (!accounts || typeof accounts !== "object") return [];
-  return Object.keys(accounts).filter(Boolean);
-}
 
+import type { ResolvedWecomAccount } from "./types/index.js";
+import {
+  listWecomAccountIds as listWecomAccountIdsFromConfig,
+  resolveDefaultWecomAccountId as resolveDefaultWecomAccountIdFromConfig,
+  resolveWecomAccount as resolveWecomAccountFromConfig,
+} from "./config/accounts.js";
+
+/**
+ * Backward-compatible re-export layer.
+ * Keep this file as a thin wrapper so older imports continue to work,
+ * while all account logic stays single-sourced in `src/config/accounts.ts`.
+ */
 export function listWecomAccountIds(cfg: OpenClawConfig): string[] {
-  const ids = listConfiguredAccountIds(cfg);
-  if (ids.length === 0) return [DEFAULT_ACCOUNT_ID];
-  return ids.sort((a, b) => a.localeCompare(b));
+  return listWecomAccountIdsFromConfig(cfg);
 }
 
 export function resolveDefaultWecomAccountId(cfg: OpenClawConfig): string {
-  const wecomConfig = cfg.channels?.wecom as WecomConfig | undefined;
-  if (wecomConfig?.defaultAccount?.trim()) return wecomConfig.defaultAccount.trim();
-  const ids = listWecomAccountIds(cfg);
-  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
-  return ids[0] ?? DEFAULT_ACCOUNT_ID;
-}
-
-function resolveAccountConfig(
-  cfg: OpenClawConfig,
-  accountId: string,
-): WecomAccountConfig | undefined {
-  const accounts = (cfg.channels?.wecom as WecomConfig | undefined)?.accounts;
-  if (!accounts || typeof accounts !== "object") return undefined;
-  return accounts[accountId] as WecomAccountConfig | undefined;
-}
-
-function mergeWecomAccountConfig(cfg: OpenClawConfig, accountId: string): WecomAccountConfig {
-  const raw = (cfg.channels?.wecom ?? {}) as WecomConfig;
-  const { accounts: _ignored, defaultAccount: _ignored2, ...base } = raw;
-  const account = resolveAccountConfig(cfg, accountId) ?? {};
-  return { ...base, ...account };
+  return resolveDefaultWecomAccountIdFromConfig(cfg);
 }
 
 export function resolveWecomAccount(params: {
   cfg: OpenClawConfig;
   accountId?: string | null;
 }): ResolvedWecomAccount {
-  const accountId = normalizeAccountId(params.accountId);
-  const baseEnabled = (params.cfg.channels?.wecom as WecomConfig | undefined)?.enabled !== false;
-  const merged = mergeWecomAccountConfig(params.cfg, accountId);
-  const enabled = baseEnabled && merged.enabled !== false;
-
-  const token = merged.token?.trim() || undefined;
-  const encodingAESKey = merged.encodingAESKey?.trim() || undefined;
-  const receiveId = merged.receiveId?.trim() ?? "";
-  const configured = Boolean(token && encodingAESKey);
-
-  return {
-    accountId,
-    name: merged.name?.trim() || undefined,
-    enabled,
-    configured,
-    token,
-    encodingAESKey,
-    receiveId,
-    config: merged,
-  };
+  return resolveWecomAccountFromConfig(params);
 }
 
 export function listEnabledWecomAccounts(cfg: OpenClawConfig): ResolvedWecomAccount[] {
-  return listWecomAccountIds(cfg)
-    .map((accountId) => resolveWecomAccount({ cfg, accountId }))
+  return listWecomAccountIdsFromConfig(cfg)
+    .map((accountId) => resolveWecomAccountFromConfig({ cfg, accountId }))
     .filter((account) => account.enabled);
 }

package/src/agent/api-client.ts

@@ -25,6 +25,11 @@ type TokenCache = {
 
 const tokenCaches = new Map<string, TokenCache>();
 
+function requireAgentId(agent: ResolvedAgentAccount): number {
+    if (typeof agent.agentId === "number" && Number.isFinite(agent.agentId)) return agent.agentId;
+    throw new Error(`wecom agent account=${agent.accountId} missing agentId; sending via cgi-bin/message/send requires agentId`);
+}
+
 /**
  * **getAccessToken (获取 AccessToken)**
  * 
@@ -35,7 +40,7 @@ const tokenCaches = new Map<string, TokenCache>();
  * @returns 有效的 AccessToken
  */
 export async function getAccessToken(agent: ResolvedAgentAccount): Promise<string> {
-    const cacheKey = `${agent.corpId}:${agent.agentId}`;
+    const cacheKey = `${agent.corpId}:${String(agent.agentId ?? "na")}`;
     let cache = tokenCaches.get(cacheKey);
 
     if (!cache) {
@@ -109,7 +114,7 @@ export async function sendText(params: {
             toparty: toParty,
             totag: toTag,
             msgtype: "text",
-            agentid: agent.agentId,
+            agentid: requireAgentId(agent),
             text: { content: text }
         };
 
@@ -252,7 +257,7 @@ export async function sendMedia(params: {
             toparty: toParty,
             totag: toTag,
             msgtype: mediaType,
-            agentid: agent.agentId,
+            agentid: requireAgentId(agent),
             [mediaType]: mediaPayload
         };
 

package/src/agent/handler.event-filter.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+
+import { shouldProcessAgentInboundMessage } from "./handler.js";
+
+describe("shouldProcessAgentInboundMessage", () => {
+    it("skips event callbacks so they do not create sessions", () => {
+        const enterAgent = shouldProcessAgentInboundMessage({
+            msgType: "event",
+            eventType: "enter_agent",
+            fromUser: "zhangsan",
+        });
+        expect(enterAgent.shouldProcess).toBe(false);
+        expect(enterAgent.reason).toBe("event:enter_agent");
+
+        const subscribe = shouldProcessAgentInboundMessage({
+            msgType: "event",
+            eventType: "subscribe",
+            fromUser: "lisi",
+        });
+        expect(subscribe.shouldProcess).toBe(false);
+        expect(subscribe.reason).toBe("event:subscribe");
+    });
+
+    it("skips system sender callbacks", () => {
+        const systemSender = shouldProcessAgentInboundMessage({
+            msgType: "text",
+            fromUser: "sys",
+        });
+        expect(systemSender.shouldProcess).toBe(false);
+        expect(systemSender.reason).toBe("system_sender");
+    });
+
+    it("skips messages with missing sender id", () => {
+        const missingSender = shouldProcessAgentInboundMessage({
+            msgType: "text",
+            fromUser: "   ",
+        });
+        expect(missingSender.shouldProcess).toBe(false);
+        expect(missingSender.reason).toBe("missing_sender");
+    });
+
+    it("allows normal user text message processing", () => {
+        const normalMessage = shouldProcessAgentInboundMessage({
+            msgType: "text",
+            fromUser: "wangwu",
+        });
+        expect(normalMessage.shouldProcess).toBe(true);
+        expect(normalMessage.reason).toBe("user_message");
+    });
+});