@wecom/wecom-openclaw-plugin 2026.3.30 → 2026.3.31-beta.1

package/dist/src/shared/command-auth.js

@@ -0,0 +1,73 @@
+function normalizeWecomAllowFromEntry(raw) {
+    return raw
+        .trim()
+        .toLowerCase()
+        .replace(/^wecom:/, "")
+        .replace(/^user:/, "")
+        .replace(/^userid:/, "");
+}
+function isWecomSenderAllowed(senderUserId, allowFrom) {
+    const list = allowFrom.map((entry) => normalizeWecomAllowFromEntry(entry)).filter(Boolean);
+    if (list.includes("*"))
+        return true;
+    const normalizedSender = normalizeWecomAllowFromEntry(senderUserId);
+    if (!normalizedSender)
+        return false;
+    return list.includes(normalizedSender);
+}
+export async function resolveWecomCommandAuthorization(params) {
+    const { core, cfg, accountConfig, rawBody, senderUserId } = params;
+    const dmPolicy = (accountConfig.dmPolicy ?? "pairing");
+    const configAllowFrom = (accountConfig.allowFrom ?? []).map((v) => String(v));
+    const shouldComputeAuth = core.channel.commands.shouldComputeCommandAuthorized(rawBody, cfg);
+    // WeCom channel currently does NOT support the `openclaw pairing` CLI workflow
+    // ("Channel wecom does not support pairing"). So we must not rely on pairing
+    // store approvals for command authorization here.
+    //
+    // Policy semantics:
+    // - open: commands are allowed for everyone by default (unless higher-level access-groups deny).
+    // - allowlist: commands require allowFrom entries.
+    // - pairing: treated the same as allowlist for WeCom (since pairing CLI is unsupported).
+    const effectiveAllowFrom = dmPolicy === "open" ? ["*"] : configAllowFrom;
+    const senderAllowed = isWecomSenderAllowed(senderUserId, effectiveAllowFrom);
+    const allowAllConfigured = effectiveAllowFrom.some((entry) => normalizeWecomAllowFromEntry(entry) === "*");
+    const authorizerConfigured = allowAllConfigured || effectiveAllowFrom.length > 0;
+    const useAccessGroups = cfg.commands?.useAccessGroups !== false;
+    const commandAuthorized = shouldComputeAuth
+        ? core.channel.commands.resolveCommandAuthorizedFromAuthorizers({
+            useAccessGroups,
+            authorizers: [{ configured: authorizerConfigured, allowed: senderAllowed }],
+        })
+        : undefined;
+    return {
+        shouldComputeAuth,
+        dmPolicy,
+        senderAllowed,
+        authorizerConfigured,
+        commandAuthorized,
+        effectiveAllowFrom,
+    };
+}
+export function buildWecomUnauthorizedCommandPrompt(params) {
+    const user = params.senderUserId || "unknown";
+    const policy = params.dmPolicy;
+    const scopeLabel = params.scope === "bot" ? "Bot（智能机器人）" : "Agent（自建应用）";
+    const dmPrefix = params.scope === "bot" ? "channels.wecom.bot" : "channels.wecom.agent";
+    const allowCmd = (value) => `openclaw config set ${dmPrefix}.allowFrom '${value}'`;
+    const policyCmd = (value) => `openclaw config set ${dmPrefix}.dmPolicy "${value}"`;
+    if (policy === "disabled") {
+        return [
+            `无权限执行命令（${scopeLabel} 已禁用：dmPolicy=disabled）`,
+            `触发者：${user}`,
+            `管理员：${policyCmd("open")}（全放开）或 ${policyCmd("allowlist")}（白名单）`,
+        ].join("\n");
+    }
+    // WeCom 不支持 pairing CLI，因此这里统一给出“open / allowlist”两种明确的配置指令
+    return [
+        `无权限执行命令（入口：${scopeLabel}，userid：${user}）`,
+        `管理员全放开：${policyCmd("open")}`,
+        `管理员放行该用户：${policyCmd("allowlist")}`,
+        `然后设置白名单：${allowCmd(JSON.stringify([user]))}`,
+        `如果仍被拦截：检查 commands.useAccessGroups/访问组`,
+    ].join("\n");
+}

package/dist/src/shared/xml-parser.d.ts

@@ -0,0 +1,46 @@
+/**
+ * WeCom XML 解析器
+ * 用于 Agent 模式解析 XML 格式消息
+ */
+import type { WecomAgentInboundMessage } from "../types/index.js";
+/**
+ * 解析 XML 字符串为消息对象
+ */
+export declare function parseXml(xml: string): WecomAgentInboundMessage;
+/**
+ * 从 XML 中提取消息类型
+ */
+export declare function extractMsgType(msg: WecomAgentInboundMessage): string;
+/**
+ * 从 XML 中提取发送者 ID
+ */
+export declare function extractFromUser(msg: WecomAgentInboundMessage): string;
+/**
+ * 从 XML 中提取文件名（主要用于 file 消息）
+ */
+export declare function extractFileName(msg: WecomAgentInboundMessage): string | undefined;
+/**
+ * 从 XML 中提取接收者 ID (CorpID)
+ */
+export declare function extractToUser(msg: WecomAgentInboundMessage): string;
+/**
+ * 从 XML 中提取群聊 ID
+ */
+export declare function extractChatId(msg: WecomAgentInboundMessage): string | undefined;
+/**
+ * 从 XML 中提取 AgentID（兼容 AgentID/agentid 等大小写）
+ */
+export declare function extractAgentId(msg: WecomAgentInboundMessage): string | number | undefined;
+/**
+ * 从 XML 中提取消息内容
+ */
+export declare function extractContent(msg: WecomAgentInboundMessage): string;
+/**
+ * 从 XML 中提取媒体 ID (Image, Voice, Video)
+ * 根据官方文档，MediaId 在 Agent 回调中直接位于根节点
+ */
+export declare function extractMediaId(msg: WecomAgentInboundMessage): string | undefined;
+/**
+ * 从 XML 中提取 MsgId（用于去重）
+ */
+export declare function extractMsgId(msg: WecomAgentInboundMessage): string | undefined;

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/src/state-dir-resolve.d.ts

@@ -0,0 +1,2 @@
+/** 解析 openclaw 状态目录 */
+export declare function resolveStateDir(): string;

package/dist/src/state-dir-resolve.js

@@ -0,0 +1,9 @@
+import * as path from "node:path";
+import * as os from "node:os";
+/** 解析 openclaw 状态目录 */
+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");
+}

package/dist/src/state-manager.js

@@ -0,0 +1,216 @@
+/**
+ * 企业微信全局状态管理模块
+ *
+ * 负责管理 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 实例管理
+// ============================================================================
+/** WSClient 实例管理 */
+const wsClientInstances = new Map();
+/**
+ * 获取指定账户的 WSClient 实例
+ */
+export function getWeComWebSocket(accountId) {
+    return wsClientInstances.get(accountId) ?? null;
+}
+/**
+ * 设置指定账户的 WSClient 实例
+ */
+export function setWeComWebSocket(accountId, client) {
+    wsClientInstances.set(accountId, client);
+}
+/**
+ * 删除指定账户的 WSClient 实例
+ */
+export function deleteWeComWebSocket(accountId) {
+    wsClientInstances.delete(accountId);
+}
+/** 消息状态管理 */
+const messageStates = new Map();
+/** 定期清理定时器 */
+let cleanupTimer = null;
+/**
+ * 启动消息状态定期清理（自动 TTL 清理 + 容量限制）
+ */
+export function startMessageStateCleanup() {
+    if (cleanupTimer)
+        return;
+    cleanupTimer = setInterval(() => {
+        pruneMessageStates();
+    }, MESSAGE_STATE_CLEANUP_INTERVAL_MS);
+    // 允许进程退出时不阻塞
+    if (cleanupTimer && typeof cleanupTimer === "object" && "unref" in cleanupTimer) {
+        cleanupTimer.unref();
+    }
+}
+/**
+ * 停止消息状态定期清理
+ */
+export function stopMessageStateCleanup() {
+    if (cleanupTimer) {
+        clearInterval(cleanupTimer);
+        cleanupTimer = null;
+    }
+}
+/**
+ * 清理过期和超量的消息状态条目
+ */
+function pruneMessageStates() {
+    const now = Date.now();
+    // 1. 清理过期条目
+    for (const [key, entry] of messageStates) {
+        if (now - entry.createdAt >= MESSAGE_STATE_TTL_MS) {
+            messageStates.delete(key);
+        }
+    }
+    // 2. 容量限制：如果仍超过最大条目数，按时间淘汰最旧的
+    if (messageStates.size > MESSAGE_STATE_MAX_SIZE) {
+        const sorted = [...messageStates.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+        const toRemove = sorted.slice(0, messageStates.size - MESSAGE_STATE_MAX_SIZE);
+        for (const [key] of toRemove) {
+            messageStates.delete(key);
+        }
+    }
+}
+/**
+ * 设置消息状态
+ */
+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;
+}
+/**
+ * 删除消息状态
+ */
+export function deleteMessageState(messageId) {
+    messageStates.delete(messageId);
+}
+/**
+ * 清空所有消息状态
+ */
+export function clearAllMessageStates() {
+    messageStates.clear();
+}
+// ============================================================================
+// ReqId 持久化存储管理（按 accountId 隔离）
+// ============================================================================
+/**
+ * ReqId 持久化存储管理
+ * 参考 createPersistentDedupe 模式：内存 + 磁盘双层、文件锁、原子写入、TTL 过期、防抖写入
+ * 重启后可从磁盘恢复，确保主动推送消息时能获取到 reqId
+ */
+const reqIdStores = new Map();
+function getOrCreateReqIdStore(accountId) {
+    let store = reqIdStores.get(accountId);
+    if (!store) {
+        store = createPersistentReqIdStore(accountId);
+        reqIdStores.set(accountId, store);
+    }
+    return store;
+}
+// ============================================================================
+// ReqId 操作函数
+// ============================================================================
+/**
+ * 设置 chatId 对应的 reqId（写入内存 + 防抖写磁盘）
+ */
+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（无预热条目）
+ */
+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（断开连接时释放所有资源）
+// ============================================================================
+/**
+ * 清理指定账户的所有资源
+ */
+export async function cleanupAccount(accountId) {
+    // 1. 断开 WSClient
+    const wsClient = wsClientInstances.get(accountId);
+    if (wsClient) {
+        try {
+            wsClient.disconnect();
+        }
+        catch {
+            // 忽略断开连接时的错误
+        }
+        wsClientInstances.delete(accountId);
+    }
+    // 2. 由于移除了磁盘存储，不再需要 flush reqId 存储
+    // 注意：不删除 store，因为重连后可能还需要
+}
+/**
+ * 清理所有资源（用于进程退出）
+ */
+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 };
+}