@wecom/wecom-openclaw-plugin 2026.4.2 → 2026.4.3-beta.0

package/dist/src/shared/xml-parser.js

@@ -0,0 +1,210 @@
+/**
+ * WeCom XML 解析器
+ * 用于 Agent 模式解析 XML 格式消息
+ */
+import { XMLParser } from "fast-xml-parser";
+const xmlParser = new XMLParser({
+    ignoreAttributes: false,
+    trimValues: true,
+    processEntities: false,
+    parseTagValue: false,
+    parseAttributeValue: false,
+});
+/**
+ * 解析 XML 字符串为消息对象
+ */
+export function parseXml(xml) {
+    const obj = xmlParser.parse(xml);
+    const root = obj?.xml ?? obj;
+    return root ?? {};
+}
+/**
+ * 从 XML 中提取消息类型
+ */
+export function extractMsgType(msg) {
+    return String(msg.MsgType ?? "").toLowerCase();
+}
+/**
+ * 从 XML 中提取发送者 ID
+ */
+export function extractFromUser(msg) {
+    return String(msg.FromUserName ?? "");
+}
+/**
+ * 从 XML 中提取文件名（主要用于 file 消息）
+ */
+export function extractFileName(msg) {
+    const raw = msg.FileName ?? msg.Filename ?? msg.fileName ?? msg.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;
+        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)
+ */
+export function extractToUser(msg) {
+    return String(msg.ToUserName ?? "");
+}
+/**
+ * 从 XML 中提取群聊 ID
+ */
+export function extractChatId(msg) {
+    return msg.ChatId ? String(msg.ChatId) : undefined;
+}
+/**
+ * 从 XML 中提取 AgentID（兼容 AgentID/agentid 等大小写）
+ */
+export function extractAgentId(msg) {
+    const raw = msg.AgentID ??
+        msg.AgentId ??
+        msg.agentid ??
+        msg.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 中提取消息内容
+ */
+export function extractContent(msg) {
+    const msgType = extractMsgType(msg);
+    const asText = (value) => {
+        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;
+            // 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 asText(msg.Content);
+        case "voice":
+            // 语音识别结果
+            return asText(msg.Recognition) || "[语音消息]";
+        case "image":
+            return `[图片] ${asText(msg.PicUrl)}`;
+        case "file":
+            return "[文件消息]";
+        case "video":
+            return "[视频消息]";
+        case "location":
+            return `[位置] ${asText(msg.Label)} (${asText(msg.Location_X)}, ${asText(msg.Location_Y)})`;
+        case "link":
+            return `[链接] ${asText(msg.Title)}\n${asText(msg.Description)}\n${asText(msg.Url)}`;
+        case "event":
+            return `[事件] ${asText(msg.Event)} - ${asText(msg.EventKey)}`;
+        default:
+            return `[${msgType || "未知消息类型"}]`;
+    }
+}
+/**
+ * 从 XML 中提取媒体 ID (Image, Voice, Video)
+ * 根据官方文档，MediaId 在 Agent 回调中直接位于根节点
+ */
+export function extractMediaId(msg) {
+    const raw = msg.MediaId ?? msg.MediaID ?? msg.mediaid ?? msg.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;
+        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) {
+    const raw = msg.MsgId ?? msg.MsgID ?? msg.msgid ?? msg.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;
+        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/dist/{esm/src → src}/state-dir-resolve.js

@@ -1,13 +1,9 @@
-import * as path from 'node:path';
-import * as os from 'node:os';
-
+import * as path from "node:path";
+import * as os from "node:os";
 /** 解析 openclaw 状态目录 */
-function resolveStateDir() {
+export function resolveStateDir() {
     const stateOverride = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim();
     if (stateOverride)
         return stateOverride;
     return path.join(os.homedir(), ".openclaw");
 }
-
-export { resolveStateDir };
-//# sourceMappingURL=state-dir-resolve.js.map

package/dist/{esm/src → src}/state-manager.js

@@ -1,12 +1,11 @@
-import { createPersistentReqIdStore } from './reqid-store.js';
-import { MESSAGE_STATE_CLEANUP_INTERVAL_MS, MESSAGE_STATE_TTL_MS, MESSAGE_STATE_MAX_SIZE } from './const.js';
-
 /**
  * 企业微信全局状态管理模块
  *
  * 负责管理 WSClient 实例、消息状态（带 TTL 清理）、ReqId 存储
  * 解决全局 Map 的内存泄漏问题
  */
+import { createPersistentReqIdStore } from "./reqid-store.js";
+import { MESSAGE_STATE_TTL_MS, MESSAGE_STATE_CLEANUP_INTERVAL_MS, MESSAGE_STATE_MAX_SIZE, } from "./const.js";
 // ============================================================================
 // WSClient 实例管理
 // ============================================================================
@@ -15,15 +14,21 @@ const wsClientInstances = new Map();
 /**
  * 获取指定账户的 WSClient 实例
  */
-function getWeComWebSocket(accountId) {
+export function getWeComWebSocket(accountId) {
     return wsClientInstances.get(accountId) ?? null;
 }
 /**
  * 设置指定账户的 WSClient 实例
  */
-function setWeComWebSocket(accountId, client) {
+export function setWeComWebSocket(accountId, client) {
     wsClientInstances.set(accountId, client);
 }
+/**
+ * 删除指定账户的 WSClient 实例
+ */
+export function deleteWeComWebSocket(accountId) {
+    wsClientInstances.delete(accountId);
+}
 /** 消息状态管理 */
 const messageStates = new Map();
 /** 定期清理定时器 */
@@ -31,7 +36,7 @@ let cleanupTimer = null;
 /**
  * 启动消息状态定期清理（自动 TTL 清理 + 容量限制）
  */
-function startMessageStateCleanup() {
+export function startMessageStateCleanup() {
     if (cleanupTimer)
         return;
     cleanupTimer = setInterval(() => {
@@ -45,7 +50,7 @@ function startMessageStateCleanup() {
 /**
  * 停止消息状态定期清理
  */
-function stopMessageStateCleanup() {
+export function stopMessageStateCleanup() {
     if (cleanupTimer) {
         clearInterval(cleanupTimer);
         cleanupTimer = null;
@@ -74,18 +79,38 @@ function pruneMessageStates() {
 /**
  * 设置消息状态
  */
-function setMessageState(messageId, state) {
+export function setMessageState(messageId, state) {
     messageStates.set(messageId, {
         state,
         createdAt: Date.now(),
     });
 }
+/**
+ * 获取消息状态
+ */
+export function getMessageState(messageId) {
+    const entry = messageStates.get(messageId);
+    if (!entry)
+        return undefined;
+    // 检查 TTL
+    if (Date.now() - entry.createdAt >= MESSAGE_STATE_TTL_MS) {
+        messageStates.delete(messageId);
+        return undefined;
+    }
+    return entry.state;
+}
 /**
  * 删除消息状态
  */
-function deleteMessageState(messageId) {
+export function deleteMessageState(messageId) {
     messageStates.delete(messageId);
 }
+/**
+ * 清空所有消息状态
+ */
+export function clearAllMessageStates() {
+    messageStates.clear();
+}
 // ============================================================================
 // ReqId 持久化存储管理（按 accountId 隔离）
 // ============================================================================
@@ -98,7 +123,7 @@ const reqIdStores = new Map();
 function getOrCreateReqIdStore(accountId) {
     let store = reqIdStores.get(accountId);
     if (!store) {
-        store = createPersistentReqIdStore();
+        store = createPersistentReqIdStore(accountId);
         reqIdStores.set(accountId, store);
     }
     return store;
@@ -109,26 +134,52 @@ function getOrCreateReqIdStore(accountId) {
 /**
  * 设置 chatId 对应的 reqId（写入内存 + 防抖写磁盘）
  */
-function setReqIdForChat(chatId, reqId, accountId = "default") {
+export function setReqIdForChat(chatId, reqId, accountId = "default") {
     getOrCreateReqIdStore(accountId).set(chatId, reqId);
 }
+/**
+ * 获取 chatId 对应的 reqId（异步：优先内存，miss 时查磁盘并回填内存）
+ */
+export async function getReqIdForChatAsync(chatId, accountId = "default") {
+    return getOrCreateReqIdStore(accountId).get(chatId);
+}
+/**
+ * 获取 chatId 对应的 reqId（同步：仅内存，保留向后兼容）
+ */
+export function getReqIdForChat(chatId, accountId = "default") {
+    return getOrCreateReqIdStore(accountId).getSync(chatId);
+}
+/**
+ * 删除 chatId 对应的 reqId
+ */
+export function deleteReqIdForChat(chatId, accountId = "default") {
+    getOrCreateReqIdStore(accountId).delete(chatId);
+}
 /**
  * 启动时预热 reqId 缓存（从磁盘加载到内存）
  *
  * 注意：由于移除了磁盘存储，此函数现在只返回 0（无预热条目）
  */
-async function warmupReqIdStore(accountId = "default", log) {
+export async function warmupReqIdStore(accountId = "default", log) {
     // 由于移除了磁盘存储，不再需要预热过程
     log?.("[WeCom] reqid-store warmup: no-op (disk storage removed)");
     return 0;
 }
+/**
+ * 立即将 reqId 数据刷写到磁盘（用于优雅退出）
+ *
+ * 注意：由于移除了磁盘存储，此函数现在是无操作
+ */
+export async function flushReqIdStore(accountId = "default") {
+    // 由于移除了磁盘存储，不再需要刷写操作
+}
 // ============================================================================
 // 全局 cleanup（断开连接时释放所有资源）
 // ============================================================================
 /**
  * 清理指定账户的所有资源
  */
-async function cleanupAccount(accountId) {
+export async function cleanupAccount(accountId) {
     // 1. 断开 WSClient
     const wsClient = wsClientInstances.get(accountId);
     if (wsClient) {
@@ -143,6 +194,23 @@ async function cleanupAccount(accountId) {
     // 2. 由于移除了磁盘存储，不再需要 flush reqId 存储
     // 注意：不删除 store，因为重连后可能还需要
 }
-
-export { cleanupAccount, deleteMessageState, getWeComWebSocket, setMessageState, setReqIdForChat, setWeComWebSocket, startMessageStateCleanup, stopMessageStateCleanup, warmupReqIdStore };
-//# sourceMappingURL=state-manager.js.map
+/**
+ * 清理所有资源（用于进程退出）
+ */
+export async function cleanupAll() {
+    // 停止定期清理
+    stopMessageStateCleanup();
+    // 清理所有 WSClient
+    for (const [accountId, wsClient] of wsClientInstances) {
+        try {
+            wsClient.disconnect();
+        }
+        catch {
+            // 忽略
+        }
+    }
+    wsClientInstances.clear();
+    // 由于移除了磁盘存储，不再需要 flush 所有 reqId 存储
+    // 清空消息状态
+    clearAllMessageStates();
+}

package/dist/src/target.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 declare function resolveWecomTarget(raw: string | undefined): WecomTarget | undefined;

package/dist/src/target.js

@@ -0,0 +1,67 @@
+/**
+ * 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) 的通知模式，而回复是具体的会话模式。
+ */
+/**
+ * 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) {
+    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/dist/src/template-card-manager.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 模板卡片管理器
+ *
+ * 负责：
+ * - 模板卡片缓存管理（内存级，带 TTL 和大小限制）
+ * - 卡片交互事件处理（更新卡片 UI 状态）
+ * - 模板卡片发送（通过 wsClient.sendMessage 主动推送）
+ * - 从 LLM 回复中检测并处理模板卡片
+ */
+import type { RuntimeEnv } from "openclaw/plugin-sdk/runtime-env";
+import type { WSClient, WsFrame, TemplateCard } from "@wecom/aibot-node-sdk";
+import type { ResolvedWeComAccount } from "./utils.js";
+import type { MessageState, ExtractedTemplateCard } from "./interface.js";
+export declare function saveTemplateCardToCache(params: {
+    accountId: string;
+    templateCard: TemplateCard;
+    runtime: RuntimeEnv;
+}): void;
+export declare function getTemplateCardFromCache(accountId: string, taskId: string): TemplateCard | undefined;
+export declare function updateTemplateCardOnEvent(params: {
+    frame: WsFrame;
+    accountId: string;
+    runtime: RuntimeEnv;
+    wsClient: WSClient;
+}): Promise<void>;
+/**
+ * 逐个发送已提取的模板卡片（通过 wsClient.sendMessage 主动推送）
+ *
+ * 发送失败不阻塞流程，仅记录错误日志。
+ */
+export declare function sendTemplateCards(params: {
+    wsClient: WSClient;
+    frame: WsFrame;
+    state: MessageState;
+    account: ResolvedWeComAccount;
+    runtime: RuntimeEnv;
+    cards: ExtractedTemplateCard[];
+}): Promise<void>;
+/**
+ * 从累积文本中检测并发送模板卡片。
+ *
+ * 在 finishThinkingStream 之前调用，将卡片处理和流关闭解耦。
+ *
+ * @returns 移除卡片代码块后的剩余文本（如果没有卡片则返回 null，表示无需修改）
+ */
+export declare function processTemplateCardsIfNeeded(params: {
+    wsClient: WSClient;
+    frame: WsFrame;
+    state: MessageState;
+    account: ResolvedWeComAccount;
+    runtime: RuntimeEnv;
+}): Promise<{
+    remainingText: string;
+    cardsDetected: boolean;
+} | null>;