@yanhaidao/wecom 2.2.3 → 2.2.5

package/src/shared/xml-parser.ts

@@ -35,6 +35,29 @@ export function extractFromUser(msg: WecomAgentInboundMessage): string {
     return String(msg.FromUserName ?? "");
 }
 
+/**
+ * 从 XML 中提取文件名（主要用于 file 消息）
+ */
+export function extractFileName(msg: WecomAgentInboundMessage): string | undefined {
+    const raw = (msg as any).FileName ?? (msg as any).Filename ?? (msg as any).fileName ?? (msg as any).filename;
+    if (raw == null) return undefined;
+    if (typeof raw === "string") return raw.trim() || undefined;
+    if (typeof raw === "number" || typeof raw === "boolean" || typeof raw === "bigint") return String(raw);
+    if (Array.isArray(raw)) {
+        const merged = raw.map((v) => (v == null ? "" : String(v))).join("\n").trim();
+        return merged || undefined;
+    }
+    if (typeof raw === "object") {
+        const obj = raw as Record<string, unknown>;
+        const text = (typeof obj["#text"] === "string" ? obj["#text"] :
+            typeof obj["_text"] === "string" ? obj["_text"] :
+                typeof obj["text"] === "string" ? obj["text"] : undefined);
+        if (text && text.trim()) return text.trim();
+    }
+    const s = String(raw);
+    return s.trim() || undefined;
+}
+
 /**
  * 从 XML 中提取接收者 ID (CorpID)
  */
@@ -55,23 +78,106 @@ export function extractChatId(msg: WecomAgentInboundMessage): string | undefined
 export function extractContent(msg: WecomAgentInboundMessage): string {
     const msgType = extractMsgType(msg);
 
+    const asText = (value: unknown): string => {
+        if (value == null) return "";
+        if (typeof value === "string") return value;
+        if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+        if (Array.isArray(value)) return value.map(asText).filter(Boolean).join("\n");
+        if (typeof value === "object") {
+            const obj = value as Record<string, unknown>;
+            // fast-xml-parser 在某些情况下（例如带属性）会把文本放在 "#text"
+            if (typeof obj["#text"] === "string") return obj["#text"];
+            if (typeof obj["_text"] === "string") return obj["_text"];
+            if (typeof obj["text"] === "string") return obj["text"];
+            try {
+                return JSON.stringify(obj);
+            } catch {
+                return String(value);
+            }
+        }
+        return String(value);
+    };
+
     switch (msgType) {
         case "text":
-            return msg.Content ?? "";
+            return asText(msg.Content);
         case "voice":
             // 语音识别结果
-            return msg.Recognition ?? "[语音消息]";
+            return asText(msg.Recognition) || "[语音消息]";
         case "image":
-            return `[图片] ${msg.PicUrl ?? ""}`;
+            return `[图片] ${asText(msg.PicUrl)}`;
+        case "file":
+            return "[文件消息]";
         case "video":
             return "[视频消息]";
         case "location":
-            return `[位置] ${msg.Label ?? ""} (${msg.Location_X}, ${msg.Location_Y})`;
+            return `[位置] ${asText(msg.Label)} (${asText(msg.Location_X)}, ${asText(msg.Location_Y)})`;
         case "link":
-            return `[链接] ${msg.Title ?? ""}\n${msg.Description ?? ""}\n${msg.Url ?? ""}`;
+            return `[链接] ${asText(msg.Title)}\n${asText(msg.Description)}\n${asText(msg.Url)}`;
         case "event":
-            return `[事件] ${msg.Event ?? ""} - ${msg.EventKey ?? ""}`;
+            return `[事件] ${asText(msg.Event)} - ${asText(msg.EventKey)}`;
         default:
             return `[${msgType || "未知消息类型"}]`;
     }
 }
+
+/**
+ * 从 XML 中提取媒体 ID (Image, Voice, Video)
+ * 根据官方文档，MediaId 在 Agent 回调中直接位于根节点
+ */
+export function extractMediaId(msg: WecomAgentInboundMessage): string | undefined {
+    const raw = (msg as any).MediaId ?? (msg as any).MediaID ?? (msg as any).mediaid ?? (msg as any).mediaId;
+    if (raw == null) return undefined;
+    if (typeof raw === "string") return raw.trim() || undefined;
+    if (typeof raw === "number" || typeof raw === "boolean" || typeof raw === "bigint") return String(raw);
+    if (Array.isArray(raw)) {
+        const merged = raw.map((v) => (v == null ? "" : String(v))).join("\n").trim();
+        return merged || undefined;
+    }
+    if (typeof raw === "object") {
+        const obj = raw as Record<string, unknown>;
+        const text = (typeof obj["#text"] === "string" ? obj["#text"] :
+            typeof obj["_text"] === "string" ? obj["_text"] :
+                typeof obj["text"] === "string" ? obj["text"] : undefined);
+        if (text && text.trim()) return text.trim();
+        try {
+            const s = JSON.stringify(obj);
+            return s.trim() || undefined;
+        } catch {
+            const s = String(raw);
+            return s.trim() || undefined;
+        }
+    }
+    const s = String(raw);
+    return s.trim() || undefined;
+}
+
+/**
+ * 从 XML 中提取 MsgId（用于去重）
+ */
+export function extractMsgId(msg: WecomAgentInboundMessage): string | undefined {
+    const raw = (msg as any).MsgId ?? (msg as any).MsgID ?? (msg as any).msgid ?? (msg as any).msgId;
+    if (raw == null) return undefined;
+    if (typeof raw === "string") return raw.trim() || undefined;
+    if (typeof raw === "number" || typeof raw === "boolean" || typeof raw === "bigint") return String(raw);
+    if (Array.isArray(raw)) {
+        const merged = raw.map((v) => (v == null ? "" : String(v))).join("\n").trim();
+        return merged || undefined;
+    }
+    if (typeof raw === "object") {
+        const obj = raw as Record<string, unknown>;
+        const text = (typeof obj["#text"] === "string" ? obj["#text"] :
+            typeof obj["_text"] === "string" ? obj["_text"] :
+                typeof obj["text"] === "string" ? obj["text"] : undefined);
+        if (text && text.trim()) return text.trim();
+        try {
+            const s = JSON.stringify(obj);
+            return s.trim() || undefined;
+        } catch {
+            const s = String(raw);
+            return s.trim() || undefined;
+        }
+    }
+    const s = String(raw);
+    return s.trim() || 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-agent|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;
@@ -79,6 +109,8 @@ export type WecomAgentInboundMessage = {
     // 图片消息
     PicUrl?: string;
     MediaId?: string;
+    // 文件消息
+    FileName?: string;
     // 语音消息
     Format?: string;
     Recognition?: string;
@@ -103,6 +135,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 };