@mocrane/wecom 2026.2.27 → 2026.3.8-4

package/src/outbound.test.ts

@@ -19,6 +19,38 @@ describe("wecomOutbound", () => {
     ).rejects.toThrow(/Agent mode/i);
   });
 
+  it("throws explicit error when outbound accountId does not exist", async () => {
+    const { wecomOutbound } = await import("./outbound.js");
+    const cfg = {
+      channels: {
+        wecom: {
+          enabled: true,
+          defaultAccount: "acct-a",
+          accounts: {
+            "acct-a": {
+              enabled: true,
+              agent: {
+                corpId: "corp-a",
+                corpSecret: "secret-a",
+                agentId: 10001,
+                token: "token-a",
+                encodingAESKey: "aes-a",
+              },
+            },
+          },
+        },
+      },
+    };
+    await expect(
+      wecomOutbound.sendText({
+        cfg,
+        accountId: "acct-missing",
+        to: "user:zhangsan",
+        text: "hello",
+      } as any),
+    ).rejects.toThrow(/account "acct-missing" not found/i);
+  });
+
   it("routes sendText to agent chatId/userid", async () => {
     const { wecomOutbound } = await import("./outbound.js");
     const api = await import("./agent/api-client.js");
@@ -140,4 +172,102 @@ describe("wecomOutbound", () => {
 
     now.mockRestore();
   });
+
+  it("uses account-scoped agent config in matrix mode", async () => {
+    const { wecomOutbound } = await import("./outbound.js");
+    const api = await import("./agent/api-client.js");
+    (api.sendText as any).mockResolvedValue(undefined);
+    (api.sendText as any).mockClear();
+
+    const cfg = {
+      channels: {
+        wecom: {
+          enabled: true,
+          defaultAccount: "acct-a",
+          accounts: {
+            "acct-a": {
+              enabled: true,
+              agent: {
+                corpId: "corp-a",
+                corpSecret: "secret-a",
+                agentId: 10001,
+                token: "token-a",
+                encodingAESKey: "aes-a",
+              },
+            },
+            "acct-b": {
+              enabled: true,
+              agent: {
+                corpId: "corp-b",
+                corpSecret: "secret-b",
+                agentId: 10002,
+                token: "token-b",
+                encodingAESKey: "aes-b",
+              },
+            },
+          },
+        },
+      },
+    };
+
+    await wecomOutbound.sendText({
+      cfg,
+      accountId: "acct-b",
+      to: "user:lisi",
+      text: "hello b",
+    } as any);
+    expect(api.sendText).toHaveBeenCalledWith(
+      expect.objectContaining({
+        toUser: "lisi",
+        agent: expect.objectContaining({
+          accountId: "acct-b",
+          agentId: 10002,
+          corpId: "corp-b",
+        }),
+      }),
+    );
+  });
+
+  it("rejects outbound when target account has matrix conflict", async () => {
+    const { wecomOutbound } = await import("./outbound.js");
+    const cfg = {
+      channels: {
+        wecom: {
+          enabled: true,
+          defaultAccount: "acct-a",
+          accounts: {
+            "acct-a": {
+              enabled: true,
+              agent: {
+                corpId: "corp-shared",
+                corpSecret: "secret-a",
+                agentId: 10001,
+                token: "token-a",
+                encodingAESKey: "aes-a",
+              },
+            },
+            "acct-b": {
+              enabled: true,
+              agent: {
+                corpId: "corp-shared",
+                corpSecret: "secret-b",
+                agentId: 10001,
+                token: "token-b",
+                encodingAESKey: "aes-b",
+              },
+            },
+          },
+        },
+      },
+    };
+
+    await expect(
+      wecomOutbound.sendText({
+        cfg,
+        accountId: "acct-b",
+        to: "user:lisi",
+        text: "hello",
+      } as any),
+    ).rejects.toThrow(/duplicate wecom agent identity/i);
+  });
 });

package/src/outbound.ts

@@ -1,20 +1,50 @@
 import type { ChannelOutboundAdapter, ChannelOutboundContext } from "openclaw/plugin-sdk";
 
 import { sendText as sendAgentText, sendMedia as sendAgentMedia, uploadMedia } from "./agent/api-client.js";
-import { resolveWecomAccounts } from "./config/index.js";
+import { resolveWecomAccount, resolveWecomAccountConflict, resolveWecomAccounts } from "./config/index.js";
 import { getWecomRuntime } from "./runtime.js";
+import { getWsClient, waitForWsConnection } from "./ws-adapter.js";
 
 import { resolveWecomTarget } from "./target.js";
 
-function resolveAgentConfigOrThrow(cfg: ChannelOutboundContext["cfg"]) {
-  const account = resolveWecomAccounts(cfg).agent;
+function resolveAgentConfigOrThrow(params: {
+  cfg: ChannelOutboundContext["cfg"];
+  accountId?: string | null;
+}) {
+  const resolvedAccounts = resolveWecomAccounts(params.cfg);
+  const conflictAccountId = params.accountId?.trim() || resolvedAccounts.defaultAccountId;
+  const conflict = resolveWecomAccountConflict({
+    cfg: params.cfg,
+    accountId: conflictAccountId,
+  });
+  if (conflict) {
+    throw new Error(conflict.message);
+  }
+
+  const requestedAccountId = params.accountId?.trim();
+  if (requestedAccountId) {
+    if (!resolvedAccounts.accounts[requestedAccountId]) {
+      throw new Error(
+        `WeCom outbound account "${requestedAccountId}" not found. Configure channels.wecom.accounts.${requestedAccountId} or use an existing accountId.`,
+      );
+    }
+  }
+  const account = resolveWecomAccount({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  }).agent;
   if (!account?.configured) {
     throw new Error(
-      "WeCom outbound requires Agent mode. Configure channels.wecom.agent (corpId/corpSecret/agentId/token/encodingAESKey).",
+      `WeCom outbound requires Agent mode for account=${params.accountId ?? "default"}. Configure channels.wecom.accounts.<accountId>.agent (or legacy channels.wecom.agent).`,
+    );
+  }
+  if (typeof account.agentId !== "number" || !Number.isFinite(account.agentId)) {
+    throw new Error(
+      `WeCom outbound requires channels.wecom.accounts.<accountId>.agent.agentId (or legacy channels.wecom.agent.agentId) for account=${params.accountId ?? account.accountId}.`,
     );
   }
   // 注意：不要在日志里输出 corpSecret 等敏感信息
-  console.log(`[wecom-outbound] Using agent config: corpId=${account.corpId}, agentId=${account.agentId}`);
+  console.log(`[wecom-outbound] Using agent config: accountId=${account.accountId}, corpId=${account.corpId}, agentId=${account.agentId}`);
   return account;
 }
 
@@ -29,10 +59,47 @@ export const wecomOutbound: ChannelOutboundAdapter = {
       return [text];
     }
   },
-  sendText: async ({ cfg, to, text }: ChannelOutboundContext) => {
+  sendText: async ({ cfg, to, text, accountId }: ChannelOutboundContext) => {
     // signal removed - not supported in current SDK
 
-    const agent = resolveAgentConfigOrThrow(cfg);
+    // ── Bot WebSocket outbound 独立路径 ──
+    // WS Bot 完全独立收发，不与 Agent 组成双模，失败时直接抛错而非 fallthrough
+    const resolvedAccount = resolveWecomAccount({ cfg, accountId });
+    const botAccount = resolvedAccount.bot;
+    if (botAccount?.connectionMode === 'websocket' && botAccount.configured) {
+      const wsClient = getWsClient(botAccount.accountId);
+      const wsTarget = resolveWecomTarget(to);
+      const chatid = wsTarget?.touser || wsTarget?.chatid;
+
+      // 如果目标是 Agent 会话（wecom-agent:），跳过 WS Bot，走 Agent outbound
+      const rawTo = typeof to === "string" ? to.trim().toLowerCase() : "";
+      if (!rawTo.startsWith("wecom-agent:")) {
+        if (!wsClient?.isConnected) {
+          console.log(`[wecom-outbound] Bot WS 未连接，等待重连... (accountId=${botAccount.accountId})`);
+          const reconnected = await waitForWsConnection(botAccount.accountId, 10_000);
+          if (!reconnected) {
+            throw new Error(`[wecom-outbound] Bot WS 等待重连超时，无法发送消息 (accountId=${botAccount.accountId})`);
+          }
+        }
+        if (!chatid) {
+          throw new Error(`[wecom-outbound] Bot WS 无法解析目标 chatid (to=${String(to)})`);
+        }
+        // 重连后重新获取 client（可能是新实例）
+        const activeClient = getWsClient(botAccount.accountId);
+        if (!activeClient?.isConnected) {
+          throw new Error(`[wecom-outbound] Bot WS 重连后仍不可用 (accountId=${botAccount.accountId})`);
+        }
+        await activeClient.sendMessage(chatid, {
+          msgtype: 'markdown',
+          markdown: { content: text },
+        });
+        console.log(`[wecom-outbound] Sent text via Bot WS to chatid=${chatid} (len=${text.length})`);
+        return { channel: "wecom", messageId: `ws-bot-${Date.now()}`, timestamp: Date.now() };
+      }
+    }
+
+    // ── Agent outbound（Webhook Bot 双模 / Agent 独立）──
+    const agent = resolveAgentConfigOrThrow({ cfg, accountId });
     const target = resolveWecomTarget(to);
     if (!target) {
       throw new Error("WeCom outbound requires a target (userid, partyid, tagid or chatid).");
@@ -98,10 +165,10 @@ export const wecomOutbound: ChannelOutboundAdapter = {
       timestamp: Date.now(),
     };
   },
-  sendMedia: async ({ cfg, to, text, mediaUrl }: ChannelOutboundContext) => {
+  sendMedia: async ({ cfg, to, text, mediaUrl, accountId }: ChannelOutboundContext) => {
     // signal removed - not supported in current SDK
 
-    const agent = resolveAgentConfigOrThrow(cfg);
+    const agent = resolveAgentConfigOrThrow({ cfg, accountId });
     const target = resolveWecomTarget(to);
     if (!target) {
       throw new Error("WeCom outbound requires a target (userid, partyid, tagid or chatid).");
@@ -149,6 +216,12 @@ export const wecomOutbound: ChannelOutboundAdapter = {
         amr: "audio/amr", mp4: "video/mp4", pdf: "application/pdf", doc: "application/msword",
         docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
         xls: "application/vnd.ms-excel", xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ppt: "application/vnd.ms-powerpoint", pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        txt: "text/plain", csv: "text/csv", tsv: "text/tab-separated-values", md: "text/markdown", json: "application/json",
+        xml: "application/xml", yaml: "application/yaml", yml: "application/yaml",
+        zip: "application/zip", rar: "application/vnd.rar", "7z": "application/x-7z-compressed",
+        tar: "application/x-tar", gz: "application/gzip", tgz: "application/gzip",
+        rtf: "application/rtf", odt: "application/vnd.oasis.opendocument.text",
       };
       contentType = mimeTypes[ext] || "application/octet-stream";
       console.log(`[wecom-outbound] Reading local file: ${mediaUrl}, ext=${ext}, contentType=${contentType}`);

package/src/shared/command-auth.ts

@@ -1,6 +1,8 @@
 import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
 
-import type { WecomAccountConfig } from "../types.js";
+import type { WecomAgentConfig, WecomBotConfig } from "../types/index.js";
+
+type WecomCommandAuthAccountConfig = Pick<WecomBotConfig, "dm"> | Pick<WecomAgentConfig, "dm">;
 
 function normalizeWecomAllowFromEntry(raw: string): string {
   return raw
@@ -22,7 +24,7 @@ function isWecomSenderAllowed(senderUserId: string, allowFrom: string[]): boolea
 export async function resolveWecomCommandAuthorization(params: {
   core: PluginRuntime;
   cfg: OpenClawConfig;
-  accountConfig: WecomAccountConfig;
+  accountConfig: WecomCommandAuthAccountConfig;
   rawBody: string;
   senderUserId: string;
 }): Promise<{

package/src/shared/xml-parser.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "vitest";
 
-import { extractContent, extractMediaId, extractMsgId } from "./xml-parser.js";
+import { extractContent, extractFromUser, extractMediaId, extractMsgId, parseXml } from "./xml-parser.js";
 
 describe("wecom xml-parser", () => {
   test("extractContent is robust to non-string Content", () => {
@@ -27,4 +27,24 @@ describe("wecom xml-parser", () => {
     const msg: any = { MsgId: 123456789 };
     expect(extractMsgId(msg)).toBe("123456789");
   });
+
+  test("parseXml preserves leading zero userid in FromUserName", () => {
+    const xml = `
+      <xml>
+        <FromUserName><![CDATA[0254571]]></FromUserName>
+      </xml>
+    `;
+    const msg = parseXml(xml);
+    expect(extractFromUser(msg)).toBe("0254571");
+  });
+
+  test("parseXml preserves 64-bit MsgId as string", () => {
+    const xml = `
+      <xml>
+        <MsgId>1234567890123456</MsgId>
+      </xml>
+    `;
+    const msg = parseXml(xml);
+    expect(extractMsgId(msg)).toBe("1234567890123456");
+  });
 });

package/src/shared/xml-parser.ts

@@ -10,6 +10,8 @@ const xmlParser = new XMLParser({
     ignoreAttributes: false,
     trimValues: true,
     processEntities: false,
+    parseTagValue: false,
+    parseAttributeValue: false,
 });
 
 /**
@@ -72,6 +74,22 @@ export function extractChatId(msg: WecomAgentInboundMessage): string | undefined
     return msg.ChatId ? String(msg.ChatId) : undefined;
 }
 
+/**
+ * 从 XML 中提取 AgentID（兼容 AgentID/agentid 等大小写）
+ */
+export function extractAgentId(msg: WecomAgentInboundMessage): string | number | undefined {
+    const raw =
+        (msg as any).AgentID ??
+        (msg as any).AgentId ??
+        (msg as any).agentid ??
+        (msg as any).agentId;
+    if (raw == null) return undefined;
+    if (typeof raw === "string") return raw.trim() || undefined;
+    if (typeof raw === "number") return raw;
+    const asString = String(raw).trim();
+    return asString || undefined;
+}
+
 /**
  * 从 XML 中提取消息内容
  */

package/src/types/account.ts

@@ -2,7 +2,13 @@
  * WeCom 账号类型定义
  */
 
-import type { WecomBotConfig, WecomAgentConfig, WecomDmConfig, WecomNetworkConfig } from "./config.js";
+import type {
+    WecomBotConfig,
+    WecomAgentConfig,
+    WecomDmConfig,
+    WecomNetworkConfig,
+    WecomAccountConfig,
+} from "./config.js";
 
 /**
  * 解析后的 Bot 账号
@@ -14,9 +20,9 @@ export type ResolvedBotAccount = {
     enabled: boolean;
     /** 是否配置完整 */
     configured: boolean;
-    /** 回调 Token */
+    /** 回调 Token (webhook 模式) */
     token: string;
-    /** 回调加密密钥 */
+    /** 回调加密密钥 (webhook 模式) */
     encodingAESKey: string;
     /** 接收者 ID */
     receiveId: string;
@@ -24,6 +30,15 @@ export type ResolvedBotAccount = {
     config: WecomBotConfig;
     /** 网络配置（来自 channels.wecom.network） */
     network?: WecomNetworkConfig;
+
+    // --- 长链接模式 (WebSocket) ---
+
+    /** 连接模式 */
+    connectionMode: 'webhook' | 'websocket';
+    /** 机器人 BotID（websocket 模式下有值） */
+    botId?: string;
+    /** 机器人 Secret（websocket 模式下有值） */
+    secret?: string;
 };
 
 /**
@@ -40,8 +55,8 @@ export type ResolvedAgentAccount = {
     corpId: string;
     /** 应用 Secret */
     corpSecret: string;
-    /** 应用 ID (数字) */
-    agentId: number;
+    /** 应用 ID (数字，可选) */
+    agentId?: number;
     /** 回调 Token */
     token: string;
     /** 回调加密密钥 */
@@ -52,23 +67,46 @@ export type ResolvedAgentAccount = {
     network?: WecomNetworkConfig;
 };
 
-/**
- * 已解析的模式状态
- */
-export type ResolvedMode = {
-    /** Bot 模式是否已配置 */
-    bot: boolean;
-    /** Agent 模式是否已配置 */
-    agent: boolean;
+/** Matrix/Legacy 的统一账号解析结果 */
+export type ResolvedWecomAccount = {
+    /** 账号 ID（用于 bindings.match.accountId） */
+    accountId: string;
+    /** 展示名称 */
+    name?: string;
+    /** 是否启用 */
+    enabled: boolean;
+    /** 是否具备至少一种可用能力（bot/agent） */
+    configured: boolean;
+    /** 原始账号配置（Matrix 条目或 Legacy 聚合） */
+    config: WecomAccountConfig;
+    /** Bot 能力 */
+    bot?: ResolvedBotAccount;
+    /** Agent 能力 */
+    agent?: ResolvedAgentAccount;
 };
 
+/** 解析模式 */
+export type ResolvedMode = "disabled" | "legacy" | "matrix";
+
 /**
- * 解析后的 WeCom 账号集合
+ * 已解析的模式状态
  */
 export type ResolvedWecomAccounts = {
-    /** Bot 模式账号 */
+    /** 当前模式 */
+    mode: ResolvedMode;
+    /** 默认账号 ID */
+    defaultAccountId: string;
+    /** 账号集合（Legacy 下仅 default） */
+    accounts: Record<string, ResolvedWecomAccount>;
+    /**
+     * 向后兼容：默认账号的 bot（历史调用点仍可读取）。
+     * Matrix 下等价于 defaultAccountId 对应账号的 bot。
+     */
     bot?: ResolvedBotAccount;
-    /** Agent 模式账号 */
+    /**
+     * 向后兼容：默认账号的 agent（历史调用点仍可读取）。
+     * Matrix 下等价于 defaultAccountId 对应账号的 agent。
+     */
     agent?: ResolvedAgentAccount;
 };
 

package/src/types/config.ts

@@ -30,15 +30,33 @@ export type WecomNetworkConfig = {
     egressProxyUrl?: string;
 };
 
+/** 路由行为配置 */
+export type WecomRoutingConfig = {
+    /**
+     * 当路由未命中 bindings（matchedBy=default）时是否拒绝继续处理。
+     * - true: fail-closed（推荐于多账号）
+     * - false: 允许回退默认 agent（历史兼容）
+     */
+    failClosedOnDefaultRoute?: boolean;
+};
+
 /**
  * Bot 模式配置 (智能体)
  * 用于接收 JSON 格式回调 + 流式回复
  */
 export type WecomBotConfig = {
-    /** 回调 Token (企微后台生成) */
-    token: string;
-    /** 回调加密密钥 (企微后台生成) */
-    encodingAESKey: string;
+    /** 智能机器人 ID（用于 Matrix 模式二次身份确认，webhook 模式） */
+    aibotid?: string;
+    /** 回调 Token (企微后台生成，webhook 模式必填) */
+    token?: string;
+    /** 回调加密密钥 (企微后台生成，webhook 模式必填) */
+    encodingAESKey?: string;
+    /**
+     * BotId 列表（可选，用于审计与告警）。
+     * - 回调路由优先由 URL + 签名决定；botIds 不参与强制拦截。
+     * - 当解密后的 aibotid 不在 botIds 中时，仅记录告警日志。
+     */
+    botIds?: string[];
     /** 接收者 ID (可选，用于解密校验) */
     receiveId?: string;
     /** 流式消息占位符 */
@@ -47,6 +65,15 @@ export type WecomBotConfig = {
     welcomeText?: string;
     /** DM 策略 */
     dm?: WecomDmConfig;
+
+    // --- 长链接模式 (WebSocket) ---
+
+    /** 连接模式：webhook（默认）或 websocket */
+    connectionMode?: 'webhook' | 'websocket';
+    /** 机器人 BotID（websocket 模式必填，企微后台获取） */
+    botId?: string;
+    /** 机器人 Secret（websocket 模式必填，企微后台获取） */
+    secret?: string;
 };
 
 /**
@@ -58,8 +85,8 @@ export type WecomAgentConfig = {
     corpId: string;
     /** 应用 Secret */
     corpSecret: string;
-    /** 应用 ID */
-    agentId: number | string;
+    /** 应用 ID（可选；不填时可接收回调，但主动发送需具备该字段） */
+    agentId?: number | string;
     /** 回调 Token (企微后台「设置API接收」) */
     token: string;
     /** 回调加密密钥 (企微后台「设置API接收」) */
@@ -93,10 +120,27 @@ export type WecomConfig = {
     bot?: WecomBotConfig;
     /** Agent 模式配置 (自建应用) */
     agent?: WecomAgentConfig;
+    /**
+     * 多账号配置（每个账号可包含 bot + agent，作为一组）。
+     * accountId 用于与 OpenClaw `bindings[].match.accountId` 对齐，从而把不同 WeCom 账号路由到不同 OpenClaw agent。
+     */
+    accounts?: Record<string, WecomAccountConfig>;
+    /** 默认账号（可选） */
+    defaultAccount?: string;
     /** 媒体处理配置 */
     media?: WecomMediaConfig;
     /** 网络配置 */
     network?: WecomNetworkConfig;
+    /** 路由配置 */
+    routing?: WecomRoutingConfig;
     /** 动态 Agent 配置 */
     dynamicAgents?: WecomDynamicAgentsConfig;
 };
+
+/** Matrix 账号条目 */
+export type WecomAccountConfig = {
+    enabled?: boolean;
+    name?: string;
+    bot?: WecomBotConfig;
+    agent?: WecomAgentConfig;
+};

package/src/types/constants.ts

@@ -4,12 +4,16 @@
 
 /** 固定 Webhook 路径 */
 export const WEBHOOK_PATHS = {
-    /** Bot 模式 (智能体) - 兼容原有路径 */
+    /** Bot 模式历史兼容路径（不再维护） */
     BOT: "/wecom",
-    /** Bot 模式备用路径 */
+    /** Bot 模式历史备用兼容路径（不再维护） */
     BOT_ALT: "/wecom/bot",
-    /** Agent 模式 (自建应用) */
+    /** Agent 模式历史兼容路径（不再维护） */
     AGENT: "/wecom/agent",
+    /** Bot 模式推荐路径前缀 */
+    BOT_PLUGIN: "/plugins/wecom/bot",
+    /** Agent 模式推荐路径前缀 */
+    AGENT_PLUGIN: "/plugins/wecom/agent",
 } as const;
 
 /** 企业微信 API 端点 */

package/src/types/index.ts

@@ -7,9 +7,11 @@ export * from "./constants.js";
 
 // 配置类型
 export type {
+    WecomAccountConfig,
     WecomDmConfig,
     WecomMediaConfig,
     WecomNetworkConfig,
+    WecomRoutingConfig,
     WecomBotConfig,
     WecomAgentConfig,
     WecomConfig,
@@ -17,6 +19,7 @@ export type {
 
 // 账号类型
 export type {
+    ResolvedWecomAccount,
     ResolvedBotAccount,
     ResolvedAgentAccount,
     ResolvedMode,