@mocrane/wecom 2026.2.5

package/src/outbound.ts

@@ -0,0 +1,200 @@
+import type { ChannelOutboundAdapter, ChannelOutboundContext } from "openclaw/plugin-sdk";
+
+import { sendText as sendAgentText, sendMedia as sendAgentMedia, uploadMedia } from "./agent/api-client.js";
+import { resolveWecomAccounts } from "./config/index.js";
+import { getWecomRuntime } from "./runtime.js";
+
+import { resolveWecomTarget } from "./target.js";
+
+function resolveAgentConfigOrThrow(cfg: ChannelOutboundContext["cfg"]) {
+  const account = resolveWecomAccounts(cfg).agent;
+  if (!account?.configured) {
+    throw new Error(
+      "WeCom outbound requires Agent mode. Configure channels.wecom.agent (corpId/corpSecret/agentId/token/encodingAESKey).",
+    );
+  }
+  // 注意：不要在日志里输出 corpSecret 等敏感信息
+  console.log(`[wecom-outbound] Using agent config: corpId=${account.corpId}, agentId=${account.agentId}`);
+  return account;
+}
+
+export const wecomOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  chunkerMode: "text",
+  textChunkLimit: 20480,
+  chunker: (text, limit) => {
+    try {
+      return getWecomRuntime().channel.text.chunkText(text, limit);
+    } catch {
+      return [text];
+    }
+  },
+  sendText: async ({ cfg, to, text }: ChannelOutboundContext) => {
+    // signal removed - not supported in current SDK
+
+    const agent = resolveAgentConfigOrThrow(cfg);
+    const target = resolveWecomTarget(to);
+    if (!target) {
+      throw new Error("WeCom outbound requires a target (userid, partyid, tagid or chatid).");
+    }
+
+    // 体验优化：/new /reset 的“New session started”回执在 OpenClaw 核心里是英文固定文案，
+    // 且通过 routeReply 走 wecom outbound（Agent 主动发送）。
+    // 在 WeCom“双模式”场景下，这会造成：
+    // - 用户在 Bot 会话发 /new，但却收到一条 Agent 私信回执（双重回复/错会话）。
+    // 因此：
+    // - Bot 会话目标：抑制该回执（Bot 会话里由 wecom 插件补中文回执）。
+    // - Agent 会话目标（wecom-agent:）：允许发送，但改写成中文。
+    let outgoingText = text;
+    const trimmed = String(outgoingText ?? "").trim();
+    const rawTo = typeof to === "string" ? to.trim().toLowerCase() : "";
+    const isAgentSessionTarget = rawTo.startsWith("wecom-agent:");
+    const looksLikeNewSessionAck =
+      /new session started/i.test(trimmed) && /model:/i.test(trimmed);
+
+    if (looksLikeNewSessionAck) {
+      if (!isAgentSessionTarget) {
+        console.log(`[wecom-outbound] Suppressed command ack to avoid Bot/Agent double-reply (len=${trimmed.length})`);
+        return { channel: "wecom", messageId: `suppressed-${Date.now()}`, timestamp: Date.now() };
+      }
+
+      const modelLabel = (() => {
+        const m = trimmed.match(/model:\s*([^\n()]+)\s*/i);
+        return m?.[1]?.trim();
+      })();
+      const rewritten = modelLabel ? `✅ 已开启新会话（模型：${modelLabel}）` : "✅ 已开启新会话。";
+      console.log(`[wecom-outbound] Rewrote command ack for agent session (len=${rewritten.length})`);
+      outgoingText = rewritten;
+    }
+
+    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=${outgoingText.length})`);
+
+    try {
+      await sendAgentText({
+        agent,
+        toUser: touser,
+        toParty: toparty,
+        toTag: totag,
+        chatId: chatid,
+        text: outgoingText,
+      });
+      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",
+      messageId: `agent-${Date.now()}`,
+      timestamp: Date.now(),
+    };
+  },
+  sendMedia: async ({ cfg, to, text, mediaUrl }: ChannelOutboundContext) => {
+    // signal removed - not supported in current SDK
+
+    const agent = resolveAgentConfigOrThrow(cfg);
+    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.");
+    }
+
+    let buffer: Buffer;
+    let contentType: string;
+    let filename: string;
+
+    // 判断是 URL 还是本地文件路径
+    const isRemoteUrl = /^https?:\/\//i.test(mediaUrl);
+
+    if (isRemoteUrl) {
+      const res = await fetch(mediaUrl, { signal: AbortSignal.timeout(30000) });
+      if (!res.ok) {
+        throw new Error(`Failed to download media: ${res.status}`);
+      }
+      buffer = Buffer.from(await res.arrayBuffer());
+      contentType = res.headers.get("content-type") || "application/octet-stream";
+      const urlPath = new URL(mediaUrl).pathname;
+      filename = urlPath.split("/").pop() || "media";
+    } else {
+      // 本地文件路径
+      const fs = await import("node:fs/promises");
+      const path = await import("node:path");
+
+      buffer = await fs.readFile(mediaUrl);
+      filename = path.basename(mediaUrl);
+
+      // 根据扩展名推断 content-type
+      const ext = path.extname(mediaUrl).slice(1).toLowerCase();
+      const mimeTypes: Record<string, string> = {
+        jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif",
+        webp: "image/webp", bmp: "image/bmp", mp3: "audio/mpeg", wav: "audio/wav",
+        amr: "audio/amr", mp4: "video/mp4", pdf: "application/pdf", doc: "application/msword",
+        docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        xls: "application/vnd.ms-excel", xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      };
+      contentType = mimeTypes[ext] || "application/octet-stream";
+      console.log(`[wecom-outbound] Reading local file: ${mediaUrl}, ext=${ext}, contentType=${contentType}`);
+    }
+
+    let mediaType: "image" | "voice" | "video" | "file" = "file";
+    if (contentType.startsWith("image/")) mediaType = "image";
+    else if (contentType.startsWith("audio/")) mediaType = "voice";
+    else if (contentType.startsWith("video/")) mediaType = "video";
+
+    const mediaId = await uploadMedia({
+      agent,
+      type: mediaType,
+      buffer,
+      filename,
+    });
+
+    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",
+      messageId: `agent-media-${Date.now()}`,
+      timestamp: Date.now(),
+    };
+  },
+};

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setWecomRuntime(next: PluginRuntime): void {
+  runtime = next;
+}
+
+export function getWecomRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("WeCom runtime not initialized");
+  }
+  return runtime;
+}

package/src/shared/command-auth.ts

@@ -0,0 +1,101 @@
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
+
+import type { WecomAccountConfig } from "../types.js";
+
+function normalizeWecomAllowFromEntry(raw: string): string {
+  return raw
+    .trim()
+    .toLowerCase()
+    .replace(/^wecom:/, "")
+    .replace(/^user:/, "")
+    .replace(/^userid:/, "");
+}
+
+function isWecomSenderAllowed(senderUserId: string, allowFrom: string[]): boolean {
+  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: {
+  core: PluginRuntime;
+  cfg: OpenClawConfig;
+  accountConfig: WecomAccountConfig;
+  rawBody: string;
+  senderUserId: string;
+}): Promise<{
+  shouldComputeAuth: boolean;
+  dmPolicy: "pairing" | "allowlist" | "open" | "disabled";
+  senderAllowed: boolean;
+  authorizerConfigured: boolean;
+  commandAuthorized: boolean | undefined;
+  effectiveAllowFrom: string[];
+}> {
+  const { core, cfg, accountConfig, rawBody, senderUserId } = params;
+
+  const dmPolicy = (accountConfig.dm?.policy ?? "pairing") as "pairing" | "allowlist" | "open" | "disabled";
+  const configAllowFrom = (accountConfig.dm?.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: {
+  senderUserId: string;
+  dmPolicy: "pairing" | "allowlist" | "open" | "disabled";
+  scope: "bot" | "agent";
+}): string {
+  const user = params.senderUserId || "unknown";
+  const policy = params.dmPolicy;
+  const scopeLabel = params.scope === "bot" ? "Bot（智能机器人）" : "Agent（自建应用）";
+  const dmPrefix = params.scope === "bot" ? "channels.wecom.bot.dm" : "channels.wecom.agent.dm";
+  const allowCmd = (value: string) => `openclaw config set ${dmPrefix}.allowFrom '${value}'`;
+  const policyCmd = (value: string) => `openclaw config set ${dmPrefix}.policy "${value}"`;
+
+  if (policy === "disabled") {
+    return [
+      `无权限执行命令（${scopeLabel} 已禁用：dm.policy=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/src/shared/index.ts

@@ -0,0 +1,5 @@
+/**
+ * WeCom Shared 模块导出
+ */
+
+export { parseXml, extractMsgType, extractFromUser, extractContent, extractChatId, extractToUser } from "./xml-parser.js";

package/src/shared/xml-parser.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "vitest";
+
+import { extractContent, extractMediaId, extractMsgId } from "./xml-parser.js";
+
+describe("wecom xml-parser", () => {
+  test("extractContent is robust to non-string Content", () => {
+    const msg: any = { MsgType: "text", Content: { "#text": "hello", "@_foo": "bar" } };
+    expect(extractContent(msg)).toBe("hello");
+  });
+
+  test("extractContent handles array content", () => {
+    const msg: any = { MsgType: "text", Content: ["a", "b"] };
+    expect(extractContent(msg)).toBe("a\nb");
+  });
+
+  test("extractContent handles file messages", () => {
+    const msg: any = { MsgType: "file", MediaId: "MEDIA123" };
+    expect(extractContent(msg)).toBe("[文件消息]");
+  });
+
+  test("extractMediaId handles object MediaId", () => {
+    const msg: any = { MediaId: { "#text": "MEDIA123", "@_foo": "bar" } };
+    expect(extractMediaId(msg)).toBe("MEDIA123");
+  });
+
+  test("extractMsgId handles number MsgId", () => {
+    const msg: any = { MsgId: 123456789 };
+    expect(extractMsgId(msg)).toBe("123456789");
+  });
+});

package/src/shared/xml-parser.ts

@@ -0,0 +1,183 @@
+/**
+ * WeCom XML 解析器
+ * 用于 Agent 模式解析 XML 格式消息
+ */
+
+import { XMLParser } from "fast-xml-parser";
+import type { WecomAgentInboundMessage } from "../types/index.js";
+
+const xmlParser = new XMLParser({
+    ignoreAttributes: false,
+    trimValues: true,
+    processEntities: false,
+});
+
+/**
+ * 解析 XML 字符串为消息对象
+ */
+export function parseXml(xml: string): WecomAgentInboundMessage {
+    const obj = xmlParser.parse(xml);
+    const root = obj?.xml ?? obj;
+    return root ?? {};
+}
+
+/**
+ * 从 XML 中提取消息类型
+ */
+export function extractMsgType(msg: WecomAgentInboundMessage): string {
+    return String(msg.MsgType ?? "").toLowerCase();
+}
+
+/**
+ * 从 XML 中提取发送者 ID
+ */
+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)
+ */
+export function extractToUser(msg: WecomAgentInboundMessage): string {
+    return String(msg.ToUserName ?? "");
+}
+
+/**
+ * 从 XML 中提取群聊 ID
+ */
+export function extractChatId(msg: WecomAgentInboundMessage): string | undefined {
+    return msg.ChatId ? String(msg.ChatId) : undefined;
+}
+
+/**
+ * 从 XML 中提取消息内容
+ */
+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 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: 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 };
+}