@yanhaidao/wecom 2.2.3 → 2.2.4

package/src/onboarding.ts

@@ -30,7 +30,7 @@ function setWecomEnabled(cfg: OpenClawConfig, enabled: boolean): OpenClawConfig
         channels: {
             ...cfg.channels,
             wecom: {
-                ...cfg.channels?.wecom,
+                ...(cfg.channels?.wecom ?? {}),
                 enabled,
             },
         },
@@ -43,7 +43,7 @@ function setWecomBotConfig(cfg: OpenClawConfig, bot: WecomBotConfig): OpenClawCo
         channels: {
             ...cfg.channels,
             wecom: {
-                ...cfg.channels?.wecom,
+                ...(cfg.channels?.wecom ?? {}),
                 enabled: true,
                 bot,
             },
@@ -57,7 +57,7 @@ function setWecomAgentConfig(cfg: OpenClawConfig, agent: WecomAgentConfig): Open
         channels: {
             ...cfg.channels,
             wecom: {
-                ...cfg.channels?.wecom,
+                ...(cfg.channels?.wecom ?? {}),
                 enabled: true,
                 agent,
             },

package/src/outbound.test.ts

@@ -40,24 +40,13 @@ describe("wecomOutbound", () => {
       },
     };
 
-    const chatResult = await wecomOutbound.sendText({
-      cfg,
-      to: "wr123",
-      text: "hello",
-    } as any);
-
-    expect(api.sendText).toHaveBeenCalledWith(
-      expect.objectContaining({
-        chatId: "wr123",
-        toUser: undefined,
-        text: "hello",
-      }),
+    // Chat ID (wr/wc) is intentionally NOT supported for Agent outbound.
+    await expect(wecomOutbound.sendText({ cfg, to: "wr123", text: "hello" } as any)).rejects.toThrow(
+      /不支持向群 chatId 发送/,
     );
-    expect(chatResult.channel).toBe("wecom");
-    expect(chatResult.messageId).toBe("agent-123");
-
-    (api.sendText as any).mockClear();
+    expect(api.sendText).not.toHaveBeenCalled();
 
+    // Test: User ID (Default)
     const userResult = await wecomOutbound.sendText({
       cfg,
       to: "userid123",
@@ -67,12 +56,45 @@ describe("wecomOutbound", () => {
       expect.objectContaining({
         chatId: undefined,
         toUser: "userid123",
+        toParty: undefined,
+        toTag: undefined,
         text: "hi",
       }),
     );
     expect(userResult.messageId).toBe("agent-123");
 
+    (api.sendText as any).mockClear();
+
+    // Test: User ID explicit
+    await wecomOutbound.sendText({ cfg, to: "user:zhangsan", text: "hi" } as any);
+    expect(api.sendText).toHaveBeenCalledWith(
+      expect.objectContaining({ toUser: "zhangsan", toParty: undefined }),
+    );
+
+    (api.sendText as any).mockClear();
+
+    // Test: Party ID (Numeric)
+    await wecomOutbound.sendText({ cfg, to: "1001", text: "hi party" } as any);
+    expect(api.sendText).toHaveBeenCalledWith(
+      expect.objectContaining({ toUser: undefined, toParty: "1001" }),
+    );
+
+    (api.sendText as any).mockClear();
+
+    // Test: Party ID Explicit
+    await wecomOutbound.sendText({ cfg, to: "party:2002", text: "hi party 2" } as any);
+    expect(api.sendText).toHaveBeenCalledWith(
+      expect.objectContaining({ toUser: undefined, toParty: "2002" }),
+    );
+
+    (api.sendText as any).mockClear();
+
+    // Test: Tag ID Explicit
+    await wecomOutbound.sendText({ cfg, to: "tag:1", text: "hi tag" } as any);
+    expect(api.sendText).toHaveBeenCalledWith(
+      expect.objectContaining({ toUser: undefined, toTag: "1" }),
+    );
+
     now.mockRestore();
   });
 });
-

package/src/outbound.ts

@@ -4,11 +4,7 @@ import { sendText as sendAgentText, sendMedia as sendAgentMedia, uploadMedia } f
 import { resolveWecomAccounts } from "./config/index.js";
 import { getWecomRuntime } from "./runtime.js";
 
-function normalizeWecomOutboundTarget(raw: string | undefined): string | undefined {
-  const trimmed = raw?.trim() ?? "";
-  if (!trimmed) return undefined;
-  return trimmed.replace(/^(wecom|wechatwork|wework|qywx):/i, "").trim() || undefined;
-}
+import { resolveWecomTarget } from "./target.js";
 
 function resolveAgentConfigOrThrow(cfg: ChannelOutboundContext["cfg"]) {
   const account = resolveWecomAccounts(cfg).agent;
@@ -17,8 +13,8 @@ function resolveAgentConfigOrThrow(cfg: ChannelOutboundContext["cfg"]) {
       "WeCom outbound requires Agent mode. Configure channels.wecom.agent (corpId/corpSecret/agentId/token/encodingAESKey).",
     );
   }
-  // DEBUG: 输出使用的 Agent 配置信息
-  console.log(`[wecom-outbound] Using agent config: corpId=${account.corpId}, agentId=${account.agentId}, corpSecret=${account.corpSecret?.slice(0, 8)}...`);
+  // 注意：不要在日志里输出 corpSecret 等敏感信息
+  console.log(`[wecom-outbound] Using agent config: corpId=${account.corpId}, agentId=${account.agentId}`);
   return account;
 }
 
@@ -33,24 +29,39 @@ export const wecomOutbound: ChannelOutboundAdapter = {
       return [text];
     }
   },
-  sendText: async ({ cfg, to, text, signal }: ChannelOutboundContext) => {
-    if (signal?.aborted) {
-      throw new Error("Outbound delivery aborted");
-    }
+  sendText: async ({ cfg, to, text }: ChannelOutboundContext) => {
+    // signal removed - not supported in current SDK
 
     const agent = resolveAgentConfigOrThrow(cfg);
-    const targetId = normalizeWecomOutboundTarget(to);
-    if (!targetId) {
-      throw new Error("WeCom outbound requires a target (userid or chatid).");
+    const target = resolveWecomTarget(to);
+    if (!target) {
+      throw new Error("WeCom outbound requires a target (userid, partyid, tagid or chatid).");
     }
 
-    const isChat = /^(wr|wc)/i.test(targetId);
-    await sendAgentText({
-      agent,
-      toUser: isChat ? undefined : targetId,
-      chatId: isChat ? targetId : undefined,
-      text,
-    });
+    const { touser, toparty, totag, chatid } = target;
+    if (chatid) {
+      throw new Error(
+        `企业微信（WeCom）Agent 主动发送不支持向群 chatId 发送（chatId=${chatid}）。` +
+          `该路径在实际环境中经常失败（例如 86008：无权限访问该会话/会话由其他应用创建）。` +
+          `请改为发送给用户（userid / user:xxx），或由 Bot 模式在群内交付。`,
+      );
+    }
+    console.log(`[wecom-outbound] Sending text to target=${JSON.stringify(target)} (len=${text.length})`);
+
+    try {
+      await sendAgentText({
+        agent,
+        toUser: touser,
+        toParty: toparty,
+        toTag: totag,
+        chatId: chatid,
+        text,
+      });
+      console.log(`[wecom-outbound] Successfully sent text to ${JSON.stringify(target)}`);
+    } catch (err) {
+      console.error(`[wecom-outbound] Failed to send text to ${JSON.stringify(target)}:`, err);
+      throw err;
+    }
 
     return {
       channel: "wecom",
@@ -58,15 +69,20 @@ export const wecomOutbound: ChannelOutboundAdapter = {
       timestamp: Date.now(),
     };
   },
-  sendMedia: async ({ cfg, to, text, mediaUrl, signal }: ChannelOutboundContext) => {
-    if (signal?.aborted) {
-      throw new Error("Outbound delivery aborted");
-    }
+  sendMedia: async ({ cfg, to, text, mediaUrl }: ChannelOutboundContext) => {
+    // signal removed - not supported in current SDK
 
     const agent = resolveAgentConfigOrThrow(cfg);
-    const targetId = normalizeWecomOutboundTarget(to);
-    if (!targetId) {
-      throw new Error("WeCom outbound requires a target (userid or chatid).");
+    const target = resolveWecomTarget(to);
+    if (!target) {
+      throw new Error("WeCom outbound requires a target (userid, partyid, tagid or chatid).");
+    }
+    if (target.chatid) {
+      throw new Error(
+        `企业微信（WeCom）Agent 主动发送不支持向群 chatId 发送（chatId=${target.chatid}）。` +
+          `该路径在实际环境中经常失败（例如 86008：无权限访问该会话/会话由其他应用创建）。` +
+          `请改为发送给用户（userid / user:xxx），或由 Bot 模式在群内交付。`,
+      );
     }
     if (!mediaUrl) {
       throw new Error("WeCom outbound requires mediaUrl.");
@@ -121,20 +137,30 @@ export const wecomOutbound: ChannelOutboundAdapter = {
       filename,
     });
 
-    const isChat = /^(wr|wc)/i.test(targetId);
-    await sendAgentMedia({
-      agent,
-      toUser: isChat ? undefined : targetId,
-      chatId: isChat ? targetId : undefined,
-      mediaId,
-      mediaType,
-      ...(mediaType === "video" && text?.trim()
-        ? {
-          title: text.trim().slice(0, 64),
-          description: text.trim().slice(0, 512),
-        }
-        : {}),
-    });
+    const { touser, toparty, totag, chatid } = target;
+    console.log(`[wecom-outbound] Sending media (${mediaType}) to ${JSON.stringify(target)} (mediaId=${mediaId})`);
+
+    try {
+      await sendAgentMedia({
+        agent,
+        toUser: touser,
+        toParty: toparty,
+        toTag: totag,
+        chatId: chatid,
+        mediaId,
+        mediaType,
+        ...(mediaType === "video" && text?.trim()
+          ? {
+            title: text.trim().slice(0, 64),
+            description: text.trim().slice(0, 512),
+          }
+          : {}),
+      });
+      console.log(`[wecom-outbound] Successfully sent media to ${JSON.stringify(target)}`);
+    } catch (err) {
+      console.error(`[wecom-outbound] Failed to send media to ${JSON.stringify(target)}:`, err);
+      throw err;
+    }
 
     return {
       channel: "wecom",

package/src/shared/xml-parser.ts

@@ -75,3 +75,11 @@ export function extractContent(msg: WecomAgentInboundMessage): string {
             return `[${msgType || "未知消息类型"}]`;
     }
 }
+
+/**
+ * 从 XML 中提取媒体 ID (Image, Voice, Video)
+ * 根据官方文档，MediaId 在 Agent 回调中直接位于根节点
+ */
+export function extractMediaId(msg: WecomAgentInboundMessage): string | undefined {
+    return msg.MediaId ? String(msg.MediaId) : undefined;
+}

package/src/target.ts

@@ -0,0 +1,80 @@
+/**
+ * WeCom Target Resolver (企业微信目标解析器)
+ * 
+ * 解析 OpenClaw 的 `to` 字段（原始目标字符串），将其转换为企业微信支持的具体接收对象。
+ * 支持显式前缀 (party:, tag: 等) 和基于规则的启发式推断。
+ * 
+ * **关于“目标发送”与“消息记录”的对应关系 (Target vs Inbound):**
+ * - **发送 (Outbound)**: 支持一对多广播 (Party/Tag)。
+ *   例如发送给 `party:1`，消息会触达该部门下所有成员。
+ * - **接收 (Inbound)**: 总是来自具体的 **用户 (User)** 或 **群聊 (Chat)**。
+ *   当成员回复部门广播消息时，可以视为一个新的单聊会话或在该成员的现有单聊中回复。
+ *   因此，Outbound Target (如 Party) 与 Inbound Source (User) 不需要也不可能 1:1 强匹配。
+ *   广播是“发后即忘” (Fire-and-Forget) 的通知模式，而回复是具体的会话模式。
+ */
+
+export interface WecomTarget {
+    touser?: string;
+    toparty?: string;
+    totag?: string;
+    chatid?: string;
+}
+
+/**
+ * Parses a raw target string into a WeComTarget object.
+ * 解析原始目标字符串为 WeComTarget 对象。
+ * 
+ * 逻辑:
+ * 1. 移除标准命名空间前缀 (wecom:, qywx: 等)。
+ * 2. 检查显式类型前缀 (party:, tag:, group:, user:)。
+ * 3. 启发式回退 (无前缀时):
+ *    - 以 "wr" 或 "wc" 开头 -> Chat ID (群聊)
+ *    - 纯数字 -> Party ID (部门)
+ *    - 其他 -> User ID (用户)
+ * 
+ * @param raw - The raw target string (e.g. "party:1", "zhangsan", "wecom:wr123")
+ */
+export function resolveWecomTarget(raw: string | undefined): WecomTarget | undefined {
+    if (!raw?.trim()) return undefined;
+
+    // 1. Remove standard namespace prefixes (移除标准命名空间前缀)
+    let clean = raw.trim().replace(/^(wecom|wechatwork|wework|qywx):/i, "");
+
+    // 2. Explicit Type Prefixes (显式类型前缀)
+    if (/^party:/i.test(clean)) {
+        return { toparty: clean.replace(/^party:/i, "").trim() };
+    }
+    if (/^dept:/i.test(clean)) {
+        return { toparty: clean.replace(/^dept:/i, "").trim() };
+    }
+    if (/^tag:/i.test(clean)) {
+        return { totag: clean.replace(/^tag:/i, "").trim() };
+    }
+    if (/^group:/i.test(clean)) {
+        return { chatid: clean.replace(/^group:/i, "").trim() };
+    }
+    if (/^chat:/i.test(clean)) {
+        return { chatid: clean.replace(/^chat:/i, "").trim() };
+    }
+    if (/^user:/i.test(clean)) {
+        return { touser: clean.replace(/^user:/i, "").trim() };
+    }
+
+    // 3. Heuristics (启发式规则)
+
+    // Chat ID typically starts with 'wr' or 'wc'
+    // 群聊 ID 通常以 'wr' (外部群) 或 'wc' 开头
+    if (/^(wr|wc)/i.test(clean)) {
+        return { chatid: clean };
+    }
+
+    // Pure digits are likely Department IDs (Parties)
+    // 纯数字优先被视为部门 ID (Parties)，方便运维配置 (如 "1" 代表根部门)
+    // 如果必须要发送给纯数字 ID 的用户，请使用显式前缀 "user:1001"
+    if (/^\d+$/.test(clean)) {
+        return { toparty: clean };
+    }
+
+    // Default to User (默认为用户)
+    return { touser: clean };
+}

package/src/types/account.ts

@@ -2,7 +2,7 @@
  * WeCom 账号类型定义
  */
 
-import type { WecomBotConfig, WecomAgentConfig, WecomDmConfig } from "./config.js";
+import type { WecomBotConfig, WecomAgentConfig, WecomDmConfig, WecomNetworkConfig } from "./config.js";
 
 /**
  * 解析后的 Bot 账号
@@ -22,6 +22,8 @@ export type ResolvedBotAccount = {
     receiveId: string;
     /** 原始配置 */
     config: WecomBotConfig;
+    /** 网络配置（来自 channels.wecom.network） */
+    network?: WecomNetworkConfig;
 };
 
 /**
@@ -46,6 +48,8 @@ export type ResolvedAgentAccount = {
     encodingAESKey: string;
     /** 原始配置 */
     config: WecomAgentConfig;
+    /** 网络配置（来自 channels.wecom.network） */
+    network?: WecomNetworkConfig;
 };
 
 /**

package/src/types/config.ts

@@ -4,6 +4,8 @@
 
 /** DM 策略配置 - 与其他渠道保持一致，仅用 allowFrom */
 export type WecomDmConfig = {
+    /** DM 策略: 'open' 允许所有人, 'pairing' 需要配对, 'allowlist' 仅允许列表, 'disabled' 禁用 */
+    policy?: 'open' | 'pairing' | 'allowlist' | 'disabled';
     /** 允许的用户列表，为空表示允许所有人 */
     allowFrom?: Array<string | number>;
 };
@@ -21,6 +23,11 @@ export type WecomNetworkConfig = {
     timeoutMs?: number;
     retries?: number;
     retryDelayMs?: number;
+    /**
+     * 出口代理（用于企业可信 IP 固定出口场景）。
+     * 示例: "http://proxy.company.local:3128"
+     */
+    egressProxyUrl?: string;
 };
 
 /**

package/src/types/global.d.ts

@@ -0,0 +1,9 @@
+
+declare global {
+    var Buffer: any;
+    namespace NodeJS {
+        interface Timeout { }
+    }
+}
+
+export { };

package/src/types/message.ts

@@ -6,6 +6,17 @@
 /**
  * Bot 模式入站消息基础结构 (JSON)
  */
+/**
+ * **WecomBotInboundBase (Bot 入站消息基类)**
+ * 
+ * Bot 模式下 JSON 格式回调的基础字段。
+ * @property msgid 消息 ID
+ * @property aibotid 机器人 ID
+ * @property chattype 会话类型: "single" | "group"
+ * @property chatid 群聊 ID (仅群组时存在)
+ * @property response_url 下行回复 URL (用于被动响应转主动推送)
+ * @property from 发送者信息
+ */
 export type WecomBotInboundBase = {
     msgid?: string;
     aibotid?: string;
@@ -14,6 +25,8 @@ export type WecomBotInboundBase = {
     response_url?: string;
     from?: { userid?: string; corpid?: string };
     msgtype?: string;
+    /** 附件数量 (部分消息存在) */
+    attachment_count?: number;
 };
 
 export type WecomBotInboundText = WecomBotInboundBase & {
@@ -42,10 +55,19 @@ export type WecomBotInboundEvent = WecomBotInboundBase & {
     };
 };
 
+/**
+ * **WecomInboundQuote (引用消息)**
+ * 
+ * 消息中引用的原始内容（如回复某条消息）。
+ * 支持引用文本、图片、混合类型、语音、文件等。
+ */
 export type WecomInboundQuote = {
     msgtype?: "text" | "image" | "mixed" | "voice" | "file";
+    /** 引用文本内容 */
     text?: { content?: string };
+    /** 引用图片 URL */
     image?: { url?: string };
+    /** 引用混合消息 (图文) */
     mixed?: {
         msg_item?: Array<{
             msgtype: "text" | "image";
@@ -53,7 +75,9 @@ export type WecomInboundQuote = {
             image?: { url?: string };
         }>;
     };
+    /** 引用语音 */
     voice?: { content?: string };
+    /** 引用文件 */
     file?: { url?: string };
 };
 
@@ -67,6 +91,12 @@ export type WecomBotInboundMessage =
 /**
  * Agent 模式入站消息结构 (解析自 XML)
  */
+/**
+ * **WecomAgentInboundMessage (Agent 入站消息)**
+ * 
+ * Agent 模式下解析自 XML 的扁平化消息结构。
+ * 键名保持 PascalCase (如 `ToUserName`)。
+ */
 export type WecomAgentInboundMessage = {
     ToUserName?: string;
     FromUserName?: string;
@@ -103,6 +133,17 @@ export type WecomAgentInboundMessage = {
 /**
  * 模板卡片类型
  */
+/**
+ * **WecomTemplateCard (模板卡片)**
+ * 
+ * 复杂的交互式卡片结构。
+ * @property card_type 卡片类型: "text_notice" | "news_notice" | "button_interaction" ...
+ * @property source 来源信息
+ * @property main_title 主标题
+ * @property sub_title_text 副标题
+ * @property horizontal_content_list 水平排列的键值列表
+ * @property button_list 按钮列表
+ */
 export type WecomTemplateCard = {
     card_type: "text_notice" | "news_notice" | "button_interaction" | "vote_interaction" | "multiple_interaction";
     source?: { icon_url?: string; desc?: string; desc_color?: number };