ylib-wecom-openclaw-plugin 2026.4.29

package/dist/src/state-manager.js

@@ -0,0 +1,413 @@
+"use strict";
+/**
+ * 企业微信全局状态管理模块
+ *
+ * 负责管理 WSClient 实例、消息状态（带 TTL 清理）、ReqId 存储
+ * 解决全局 Map 的内存泄漏问题
+ */
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __spreadArrays = (this && this.__spreadArrays) || function () {
+    for (var s = 0, i = 0, il = arguments.length; i < il; i++) s += arguments[i].length;
+    for (var r = Array(s), k = 0, i = 0; i < il; i++)
+        for (var a = arguments[i], j = 0, jl = a.length; j < jl; j++, k++)
+            r[k] = a[j];
+    return r;
+};
+var _a;
+exports.__esModule = true;
+exports.cleanupAll = exports.cleanupAccount = exports.deleteSessionChatInfo = exports.getSessionChatInfo = exports.setSessionChatInfo = exports.flushReqIdStore = exports.warmupReqIdStore = exports.deleteReqIdForChat = exports.getReqIdForChat = exports.getReqIdForChatAsync = exports.setReqIdForChat = exports.clearAllMessageStates = exports.deleteMessageState = exports.getMessageState = exports.setMessageState = exports.stopMessageStateCleanup = exports.startMessageStateCleanup = exports.deleteWeComConnectionSnapshot = exports.getWeComConnectionSnapshot = exports.updateWeComConnectionSnapshot = exports.deleteWeComWebSocket = exports.setWeComWebSocket = exports.getWeComWebSocket = void 0;
+var reqid_store_js_1 = require("./reqid-store.js");
+var const_js_1 = require("./const.js");
+// ============================================================================
+// 全局单例状态（通过 globalThis + Symbol.for 确保跨 jiti loader 实例共享）
+//
+// 问题背景：openclaw 框架在不同阶段（主加载、configSchema 加载等）会创建
+// 多个独立的 jiti loader 实例，每个实例有独立的模块缓存（parentCache），
+// 导致本模块被多次实例化，模块级变量不共享。
+// 使用 globalThis + Symbol.for 可以确保同一进程内只有一份状态。
+// ============================================================================
+/** 全局共享状态的唯一键 */
+var SHARED_STATE_KEY = Symbol["for"]("wecom-openclaw-plugin:shared-state:v1");
+/**
+ * 获取或创建全局共享状态（进程内单例）
+ */
+function getSharedState() {
+    var existing = globalThis[SHARED_STATE_KEY];
+    if (existing)
+        return existing;
+    var state = {
+        wsClientInstances: new Map(),
+        messageStates: new Map(),
+        cleanupTimer: null,
+        reqIdStores: new Map(),
+        connectionSnapshots: new Map()
+    };
+    globalThis[SHARED_STATE_KEY] = state;
+    return state;
+}
+/** 进程内唯一的共享状态 */
+var shared = getSharedState();
+// ============================================================================
+// WSClient 实例管理
+// ============================================================================
+/** WSClient 实例管理 */
+var wsClientInstances = ((_a = globalThis[const_js_1.GLOBAL_WS_CLIENT_KEY]) !== null && _a !== void 0 ? _a : (globalThis[const_js_1.GLOBAL_WS_CLIENT_KEY] = new Map()));
+/**
+ * 获取指定账户的 WSClient 实例
+ */
+function getWeComWebSocket(accountId) {
+    var _a;
+    return (_a = shared.wsClientInstances.get(accountId)) !== null && _a !== void 0 ? _a : null;
+}
+exports.getWeComWebSocket = getWeComWebSocket;
+/**
+ * 设置指定账户的 WSClient 实例
+ */
+function setWeComWebSocket(accountId, client) {
+    shared.wsClientInstances.set(accountId, client);
+}
+exports.setWeComWebSocket = setWeComWebSocket;
+/**
+ * 删除指定账户的 WSClient 实例
+ */
+function deleteWeComWebSocket(accountId) {
+    shared.wsClientInstances["delete"](accountId);
+}
+exports.deleteWeComWebSocket = deleteWeComWebSocket;
+function updateWeComConnectionSnapshot(accountId, patch) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    var id = String(accountId || "").trim();
+    var previous = shared.connectionSnapshots.get(id);
+    var next = __assign({ accountId: id, connected: (_a = previous === null || previous === void 0 ? void 0 : previous.connected) !== null && _a !== void 0 ? _a : false, authenticated: (_b = previous === null || previous === void 0 ? void 0 : previous.authenticated) !== null && _b !== void 0 ? _b : false, running: (_c = previous === null || previous === void 0 ? void 0 : previous.running) !== null && _c !== void 0 ? _c : false, restartPending: (_d = previous === null || previous === void 0 ? void 0 : previous.restartPending) !== null && _d !== void 0 ? _d : false, lastEvent: (_e = previous === null || previous === void 0 ? void 0 : previous.lastEvent) !== null && _e !== void 0 ? _e : null, lastEventAt: (_f = previous === null || previous === void 0 ? void 0 : previous.lastEventAt) !== null && _f !== void 0 ? _f : null, lastStartAt: (_g = previous === null || previous === void 0 ? void 0 : previous.lastStartAt) !== null && _g !== void 0 ? _g : null, lastStopAt: (_h = previous === null || previous === void 0 ? void 0 : previous.lastStopAt) !== null && _h !== void 0 ? _h : null, lastError: (_j = previous === null || previous === void 0 ? void 0 : previous.lastError) !== null && _j !== void 0 ? _j : null, reconnectAttempts: (_k = previous === null || previous === void 0 ? void 0 : previous.reconnectAttempts) !== null && _k !== void 0 ? _k : 0 }, patch);
+    if (id) {
+        shared.connectionSnapshots.set(id, next);
+    }
+    return next;
+}
+exports.updateWeComConnectionSnapshot = updateWeComConnectionSnapshot;
+function getWeComConnectionSnapshot(accountId) {
+    var _a;
+    var id = String(accountId || "").trim();
+    if (!id)
+        return null;
+    return (_a = shared.connectionSnapshots.get(id)) !== null && _a !== void 0 ? _a : null;
+}
+exports.getWeComConnectionSnapshot = getWeComConnectionSnapshot;
+function deleteWeComConnectionSnapshot(accountId) {
+    var id = String(accountId || "").trim();
+    if (!id)
+        return;
+    shared.connectionSnapshots["delete"](id);
+}
+exports.deleteWeComConnectionSnapshot = deleteWeComConnectionSnapshot;
+// ============================================================================
+// 消息状态管理（带 TTL 清理，防止内存泄漏）
+// ============================================================================
+// MessageStateEntry 接口已在上方 SharedState 定义处声明
+/**
+ * 启动消息状态定期清理（自动 TTL 清理 + 容量限制）
+ */
+function startMessageStateCleanup() {
+    if (shared.cleanupTimer)
+        return;
+    shared.cleanupTimer = setInterval(function () {
+        pruneMessageStates();
+    }, const_js_1.MESSAGE_STATE_CLEANUP_INTERVAL_MS);
+    // 允许进程退出时不阻塞
+    if (shared.cleanupTimer && typeof shared.cleanupTimer === "object" && "unref" in shared.cleanupTimer) {
+        shared.cleanupTimer.unref();
+    }
+}
+exports.startMessageStateCleanup = startMessageStateCleanup;
+/**
+ * 停止消息状态定期清理
+ */
+function stopMessageStateCleanup() {
+    if (shared.cleanupTimer) {
+        clearInterval(shared.cleanupTimer);
+        shared.cleanupTimer = null;
+    }
+}
+exports.stopMessageStateCleanup = stopMessageStateCleanup;
+/**
+ * 清理过期和超量的消息状态条目
+ */
+function pruneMessageStates() {
+    var now = Date.now();
+    // 1. 清理过期条目
+    for (var _i = 0, _a = shared.messageStates; _i < _a.length; _i++) {
+        var _b = _a[_i], key = _b[0], entry = _b[1];
+        if (now - entry.createdAt >= const_js_1.MESSAGE_STATE_TTL_MS) {
+            shared.messageStates["delete"](key);
+        }
+    }
+    // 2. 容量限制：如果仍超过最大条目数，按时间淘汰最旧的
+    if (shared.messageStates.size > const_js_1.MESSAGE_STATE_MAX_SIZE) {
+        var sorted = __spreadArrays(shared.messageStates.entries()).sort(function (a, b) { return a[1].createdAt - b[1].createdAt; });
+        var toRemove = sorted.slice(0, shared.messageStates.size - const_js_1.MESSAGE_STATE_MAX_SIZE);
+        for (var _c = 0, toRemove_1 = toRemove; _c < toRemove_1.length; _c++) {
+            var key = toRemove_1[_c][0];
+            shared.messageStates["delete"](key);
+        }
+    }
+}
+/**
+ * 设置消息状态
+ */
+function setMessageState(messageId, state) {
+    shared.messageStates.set(messageId, {
+        state: state,
+        createdAt: Date.now()
+    });
+}
+exports.setMessageState = setMessageState;
+/**
+ * 获取消息状态
+ */
+function getMessageState(messageId) {
+    var entry = shared.messageStates.get(messageId);
+    if (!entry)
+        return undefined;
+    // 检查 TTL
+    if (Date.now() - entry.createdAt >= const_js_1.MESSAGE_STATE_TTL_MS) {
+        shared.messageStates["delete"](messageId);
+        return undefined;
+    }
+    return entry.state;
+}
+exports.getMessageState = getMessageState;
+/**
+ * 删除消息状态
+ */
+function deleteMessageState(messageId) {
+    shared.messageStates["delete"](messageId);
+}
+exports.deleteMessageState = deleteMessageState;
+/**
+ * 清空所有消息状态
+ */
+function clearAllMessageStates() {
+    shared.messageStates.clear();
+}
+exports.clearAllMessageStates = clearAllMessageStates;
+// ============================================================================
+// ReqId 持久化存储管理（按 accountId 隔离）
+// ============================================================================
+/**
+ * ReqId 持久化存储管理
+ * 参考 createPersistentDedupe 模式：内存 + 磁盘双层、文件锁、原子写入、TTL 过期、防抖写入
+ * 重启后可从磁盘恢复，确保主动推送消息时能获取到 reqId
+ */
+function getOrCreateReqIdStore(accountId) {
+    var store = shared.reqIdStores.get(accountId);
+    if (!store) {
+        store = reqid_store_js_1.createPersistentReqIdStore(accountId);
+        shared.reqIdStores.set(accountId, store);
+    }
+    return store;
+}
+// ============================================================================
+// ReqId 操作函数
+// ============================================================================
+/**
+ * 设置 chatId 对应的 reqId（写入内存 + 防抖写磁盘）
+ */
+function setReqIdForChat(chatId, reqId, accountId) {
+    if (accountId === void 0) { accountId = "default"; }
+    getOrCreateReqIdStore(accountId).set(chatId, reqId);
+}
+exports.setReqIdForChat = setReqIdForChat;
+/**
+ * 获取 chatId 对应的 reqId（异步：优先内存，miss 时查磁盘并回填内存）
+ */
+function getReqIdForChatAsync(chatId, accountId) {
+    if (accountId === void 0) { accountId = "default"; }
+    return __awaiter(this, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            return [2 /*return*/, getOrCreateReqIdStore(accountId).get(chatId)];
+        });
+    });
+}
+exports.getReqIdForChatAsync = getReqIdForChatAsync;
+/**
+ * 获取 chatId 对应的 reqId（同步：仅内存，保留向后兼容）
+ */
+function getReqIdForChat(chatId, accountId) {
+    if (accountId === void 0) { accountId = "default"; }
+    return getOrCreateReqIdStore(accountId).getSync(chatId);
+}
+exports.getReqIdForChat = getReqIdForChat;
+/**
+ * 删除 chatId 对应的 reqId
+ */
+function deleteReqIdForChat(chatId, accountId) {
+    if (accountId === void 0) { accountId = "default"; }
+    getOrCreateReqIdStore(accountId)["delete"](chatId);
+}
+exports.deleteReqIdForChat = deleteReqIdForChat;
+/**
+ * 启动时预热 reqId 缓存（从磁盘加载到内存）
+ *
+ * 注意：由于移除了磁盘存储，此函数现在只返回 0（无预热条目）
+ */
+function warmupReqIdStore(accountId, log) {
+    if (accountId === void 0) { accountId = "default"; }
+    return __awaiter(this, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            // 由于移除了磁盘存储，不再需要预热过程
+            log === null || log === void 0 ? void 0 : log("[WeCom] reqid-store warmup: no-op (disk storage removed)");
+            return [2 /*return*/, 0];
+        });
+    });
+}
+exports.warmupReqIdStore = warmupReqIdStore;
+/**
+ * 立即将 reqId 数据刷写到磁盘（用于优雅退出）
+ *
+ * 注意：由于移除了磁盘存储，此函数现在是无操作
+ */
+function flushReqIdStore(accountId) {
+    if (accountId === void 0) { accountId = "default"; }
+    return __awaiter(this, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            return [2 /*return*/];
+        });
+    });
+}
+exports.flushReqIdStore = flushReqIdStore;
+/** sessionKey → SessionChatInfo 映射 */
+var sessionChatInfoMap = new Map();
+/** 容量上限，超出按插入顺序淘汰最旧项，避免长时间运行内存增长 */
+var SESSION_CHAT_INFO_MAX_SIZE = 5000;
+/**
+ * 记录 sessionKey 对应的原始会话信息（由 monitor.ts 在消息入站时调用）
+ */
+function setSessionChatInfo(sessionKey, info) {
+    if (!sessionKey)
+        return;
+    // 容量控制：超限时淘汰最早插入的条目（Map 保留插入顺序）
+    if (sessionChatInfoMap.size >= SESSION_CHAT_INFO_MAX_SIZE && !sessionChatInfoMap.has(sessionKey)) {
+        var oldestKey = sessionChatInfoMap.keys().next().value;
+        if (oldestKey !== undefined) {
+            sessionChatInfoMap["delete"](oldestKey);
+        }
+    }
+    sessionChatInfoMap.set(sessionKey, info);
+}
+exports.setSessionChatInfo = setSessionChatInfo;
+/**
+ * 获取 sessionKey 对应的原始会话信息（由 registerTool 闭包调用）
+ */
+function getSessionChatInfo(sessionKey) {
+    if (!sessionKey)
+        return undefined;
+    return sessionChatInfoMap.get(sessionKey);
+}
+exports.getSessionChatInfo = getSessionChatInfo;
+/**
+ * 删除 sessionKey 对应的会话信息（会话结束时可选调用）
+ */
+function deleteSessionChatInfo(sessionKey) {
+    sessionChatInfoMap["delete"](sessionKey);
+}
+exports.deleteSessionChatInfo = deleteSessionChatInfo;
+// ============================================================================
+// 全局 cleanup 原始位置
+// ============================================================================
+/**
+ * 清理指定账户的所有资源
+ */
+function cleanupAccount(accountId) {
+    return __awaiter(this, void 0, void 0, function () {
+        var wsClient;
+        return __generator(this, function (_a) {
+            wsClient = shared.wsClientInstances.get(accountId);
+            if (wsClient) {
+                try {
+                    wsClient.disconnect();
+                }
+                catch (_b) {
+                    // 忽略断开连接时的错误
+                }
+                shared.wsClientInstances["delete"](accountId);
+            }
+            return [2 /*return*/];
+        });
+    });
+}
+exports.cleanupAccount = cleanupAccount;
+/**
+ * 清理所有资源（用于进程退出）
+ */
+function cleanupAll() {
+    return __awaiter(this, void 0, void 0, function () {
+        var _i, _a, _b, accountId, wsClient;
+        return __generator(this, function (_c) {
+            // 停止定期清理
+            stopMessageStateCleanup();
+            // 清理所有 WSClient
+            for (_i = 0, _a = shared.wsClientInstances; _i < _a.length; _i++) {
+                _b = _a[_i], accountId = _b[0], wsClient = _b[1];
+                try {
+                    wsClient.disconnect();
+                }
+                catch (_d) {
+                    // 忽略
+                }
+            }
+            shared.wsClientInstances.clear();
+            shared.connectionSnapshots.clear();
+            // 由于移除了磁盘存储，不再需要 flush 所有 reqId 存储
+            // 清空消息状态
+            clearAllMessageStates();
+            return [2 /*return*/];
+        });
+    });
+}
+exports.cleanupAll = cleanupAll;

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,71 @@
+"use strict";
+/**
+ * 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) 的通知模式，而回复是具体的会话模式。
+ */
+exports.__esModule = true;
+exports.resolveWecomTarget = void 0;
+/**
+ * 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")
+ */
+function resolveWecomTarget(raw) {
+    if (!(raw === null || raw === void 0 ? void 0 : raw.trim()))
+        return undefined;
+    // 1. Remove standard namespace prefixes (移除标准命名空间前缀)
+    var 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 };
+}
+exports.resolveWecomTarget = resolveWecomTarget;

package/dist/src/template-card-manager.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 模板卡片管理器
+ *
+ * 负责：
+ * - 模板卡片缓存管理（内存级，带 TTL 和大小限制）
+ * - 卡片交互事件处理（更新卡片 UI 状态）
+ * - 模板卡片发送（通过 wsClient.sendMessage 主动推送）
+ * - 从 LLM 回复中检测并处理模板卡片
+ */
+import type { RuntimeEnv } from "ylib-openclaw/plugin-sdk";
+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>;