@wecom/wecom-openclaw-plugin 2026.4.2 → 2026.4.3

package/dist/src/accounts.js

@@ -0,0 +1,222 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { CHANNEL_ID } from "./const.js";
+import { DefaultWsUrl } from "./utils.js";
+// ============================================================================
+// 账号列举
+// ============================================================================
+/**
+ * 列出 accounts 字段中配置的所有账号 ID（已 normalize）。
+ */
+function listConfiguredAccountIds(cfg) {
+    const accounts = cfg.channels?.[CHANNEL_ID]?.accounts;
+    if (!accounts || typeof accounts !== "object") {
+        return [];
+    }
+    return Object.keys(accounts).filter(Boolean).map(normalizeAccountId);
+}
+/**
+ * 判断是否为多账号模式（即配置中存在 accounts 字段）。
+ * 用于区分单账号/多账号模式的分支判断，替代 `accountId === DEFAULT_ACCOUNT_ID` 的不可靠判断。
+ */
+export function hasMultiAccounts(cfg) {
+    return listConfiguredAccountIds(cfg).length > 0;
+}
+/**
+ * 列出所有企业微信账号 ID。
+ * 如果没有 accounts 字段，返回 [DEFAULT_ACCOUNT_ID] 以向后兼容。
+ */
+export function listWeComAccountIds(cfg) {
+    const ids = listConfiguredAccountIds(cfg);
+    if (ids.length === 0) {
+        // 向后兼容：未配置 accounts 时使用默认账号
+        return [DEFAULT_ACCOUNT_ID];
+    }
+    return [...ids].sort((a, b) => a.localeCompare(b));
+}
+// ============================================================================
+// 默认账号解析
+// ============================================================================
+/**
+ * 解析默认账号 ID。
+ *
+ * 优先级：
+ * 1. 显式设置的 defaultAccount
+ * 2. 包含 DEFAULT_ACCOUNT_ID 的账号列表
+ * 3. 字母序第一个账号
+ */
+export function resolveDefaultWeComAccountId(cfg) {
+    const wecomConfig = cfg.channels?.[CHANNEL_ID];
+    const preferred = wecomConfig?.defaultAccount?.trim();
+    if (preferred) {
+        return normalizeAccountId(preferred);
+    }
+    const ids = listWeComAccountIds(cfg);
+    if (ids.includes(DEFAULT_ACCOUNT_ID)) {
+        return DEFAULT_ACCOUNT_ID;
+    }
+    return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+// ============================================================================
+// 配置合并
+// ============================================================================
+/**
+ * 合并顶层配置与账号级配置（账号级覆盖顶层）。
+ *
+ * 顶层字段（如 dmPolicy、allowFrom）作为所有账号的默认值，
+ * accounts.xxx 中的字段会覆盖顶层的同名字段。
+ * 对于 groups 等嵌套 Record 对象，使用深层合并（账号级条目覆盖同 key，但不丢失基础配置中的其他 key）。
+ */
+function mergeWeComAccountConfig(cfg, accountId) {
+    const wecomConfig = cfg.channels?.[CHANNEL_ID];
+    // 提取基础配置（排除 accounts 和 defaultAccount 字段避免递归）
+    const { accounts: _ignored, defaultAccount: _da, ...base } = wecomConfig ?? {};
+    // 查找账号级覆盖（支持 normalize 后的 key 匹配）
+    const account = findAccountConfig(wecomConfig?.accounts, accountId);
+    // 深层合并：对 groups 做嵌套合并，其余字段用账号级覆盖
+    const { groups: baseGroups, ...baseRest } = base;
+    const { groups: accountGroups, ...accountRest } = account;
+    const mergedGroups = baseGroups || accountGroups
+        ? { ...baseGroups, ...accountGroups }
+        : undefined;
+    return {
+        ...baseRest,
+        ...accountRest,
+        ...(mergedGroups !== undefined ? { groups: mergedGroups } : {}),
+    };
+}
+/**
+ * 在 accounts Record 中按 normalize 后的 accountId 查找配置。
+ * 避免因大小写差异导致找不到账号。
+ */
+function findAccountConfig(accounts, accountId) {
+    if (!accounts)
+        return {};
+    // 精确匹配优先
+    if (accounts[accountId])
+        return accounts[accountId];
+    // normalize 后匹配
+    const normalized = normalizeAccountId(accountId);
+    for (const [key, value] of Object.entries(accounts)) {
+        if (normalizeAccountId(key) === normalized)
+            return value;
+    }
+    return {};
+}
+// ============================================================================
+// 账号解析
+// ============================================================================
+/**
+ * 解析单个企业微信账号的完整配置。
+ *
+ * 支持：
+ * - 显式指定 accountId → 使用该 accountId
+ * - 未指定 → 使用默认账号
+ * - 单账号模式（无 accounts 字段） → 直接读取顶层配置
+ */
+export function resolveWeComAccountMulti(params) {
+    const hasExplicitId = typeof params.accountId === "string" && params.accountId.trim() !== "";
+    const accountId = hasExplicitId
+        ? normalizeAccountId(params.accountId)
+        : resolveDefaultWeComAccountId(params.cfg);
+    const wecomConfig = params.cfg.channels?.[CHANNEL_ID];
+    // 顶层 enabled 状态
+    const baseEnabled = wecomConfig?.enabled !== false;
+    // 合并配置
+    const merged = mergeWeComAccountConfig(params.cfg, accountId);
+    // 账号级 enabled 状态
+    const accountEnabled = merged.enabled !== false;
+    // 解析 Agent 子配置
+    const agentCfg = merged.agent;
+    let agent;
+    if (agentCfg?.corpId && agentCfg?.corpSecret && agentCfg?.token && agentCfg?.encodingAESKey) {
+        agent = {
+            accountId,
+            enabled: baseEnabled && accountEnabled,
+            configured: true,
+            corpId: agentCfg.corpId,
+            corpSecret: agentCfg.corpSecret,
+            agentId: typeof agentCfg.agentId === "string" ? Number(agentCfg.agentId) || undefined : agentCfg.agentId,
+            token: agentCfg.token,
+            encodingAESKey: agentCfg.encodingAESKey,
+            config: agentCfg,
+            network: merged.network,
+        };
+    }
+    return {
+        accountId,
+        name: merged.name ?? "企业微信",
+        enabled: baseEnabled && accountEnabled,
+        websocketUrl: merged.websocketUrl || DefaultWsUrl,
+        botId: merged.botId ?? "",
+        secret: merged.secret ?? "",
+        sendThinkingMessage: merged.sendThinkingMessage ?? true,
+        config: merged,
+        agent,
+        token: merged.token ?? "",
+        encodingAESKey: merged.encodingAESKey ?? "",
+        receiveId: merged.receiveId ?? "",
+    };
+}
+// ============================================================================
+// 批量查询
+// ============================================================================
+/**
+ * 列出所有已启用且已配置凭据的账号。
+ */
+export function listEnabledWeComAccounts(cfg) {
+    return listWeComAccountIds(cfg)
+        .map((accountId) => resolveWeComAccountMulti({ cfg, accountId }))
+        .filter((account) => {
+        if (!account.enabled)
+            return false;
+        const hasBotCredentials = Boolean(account.botId?.trim() && account.secret?.trim());
+        const hasAgentCredentials = Boolean(account.agent?.configured);
+        return hasBotCredentials || hasAgentCredentials;
+    });
+}
+// ============================================================================
+// 配置写入（多账号感知）
+// ============================================================================
+/**
+ * 写入企业微信账户配置（自动区分单账号/多账号模式）。
+ *
+ * - 单账号模式（无 accounts 字段）：写入顶层 channels.wecom
+ * - 多账号模式：写入 channels.wecom.accounts[accountId]
+ *
+ * @param cfg  当前全局配置
+ * @param updates  要写入的部分配置字段
+ * @param accountId  目标账号 ID（默认写入默认账号）
+ */
+export function setWeComAccountMulti(cfg, updates, accountId) {
+    const resolvedAccountId = accountId ?? resolveDefaultWeComAccountId(cfg);
+    const isMulti = hasMultiAccounts(cfg);
+    if (!isMulti) {
+        // 单账号模式：合并到顶层
+        const existing = (cfg.channels?.[CHANNEL_ID] ?? {});
+        const merged = { ...existing, ...updates };
+        return {
+            ...cfg,
+            channels: {
+                ...cfg.channels,
+                [CHANNEL_ID]: merged,
+            },
+        };
+    }
+    // 多账号模式：合并到 accounts[accountId]
+    const wecomConfig = (cfg.channels?.[CHANNEL_ID] ?? {});
+    const existingAccount = wecomConfig.accounts?.[resolvedAccountId] ?? {};
+    const mergedAccount = { ...existingAccount, ...updates };
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            [CHANNEL_ID]: {
+                ...wecomConfig,
+                accounts: {
+                    ...wecomConfig.accounts,
+                    [resolvedAccountId]: mergedAccount,
+                },
+            },
+        },
+    };
+}

package/dist/src/agent/api-client.d.ts

@@ -0,0 +1,94 @@
+/**
+ * WeCom Agent API 客户端
+ * 管理 AccessToken 缓存和 API 调用
+ */
+import type { ResolvedAgentAccount } from "../types/index.js";
+/**
+ * **getAccessToken (获取 AccessToken)**
+ *
+ * 获取企业微信 API 调用所需的 AccessToken。
+ * 具备自动缓存和过期刷新机制。
+ *
+ * @param agent Agent 账号信息
+ * @returns 有效的 AccessToken
+ */
+export declare function getAccessToken(agent: ResolvedAgentAccount): Promise<string>;
+/**
+ * **sendText (发送文本消息)**
+ *
+ * 调用 `message/send` (Agent) 或 `appchat/send` (群聊) 发送文本。
+ *
+ * @param params.agent 发送方 Agent
+ * @param params.toUser 接收用户 ID (单聊可选，可与 toParty/toTag 同时使用)
+ * @param params.toParty 接收部门 ID (单聊可选)
+ * @param params.toTag 接收标签 ID (单聊可选)
+ * @param params.chatId 接收群 ID (群聊模式必填，互斥)
+ * @param params.text 消息内容
+ */
+export declare function sendText(params: {
+    agent: ResolvedAgentAccount;
+    toUser?: string;
+    toParty?: string;
+    toTag?: string;
+    chatId?: string;
+    text: string;
+}): Promise<void>;
+/**
+ * **uploadMedia (上传媒体文件)**
+ *
+ * 上传临时素材到企业微信。
+ * 素材有效期为 3 天。
+ *
+ * @param params.type 媒体类型 (image, voice, video, file)
+ * @param params.buffer 文件二进制数据
+ * @param params.filename 文件名 (需包含正确扩展名)
+ * @returns 媒体 ID (media_id)
+ */
+export declare function uploadMedia(params: {
+    agent: ResolvedAgentAccount;
+    type: "image" | "voice" | "video" | "file";
+    buffer: Buffer;
+    filename: string;
+}): Promise<string>;
+/**
+ * **sendMedia (发送媒体消息)**
+ *
+ * 发送图片、音频、视频或文件。需先通过 `uploadMedia` 获取 media_id。
+ *
+ * @param params.agent 发送方 Agent
+ * @param params.toUser 接收用户 ID (单聊可选)
+ * @param params.toParty 接收部门 ID (单聊可选)
+ * @param params.toTag 接收标签 ID (单聊可选)
+ * @param params.chatId 接收群 ID (群聊模式必填)
+ * @param params.mediaId 媒体 ID
+ * @param params.mediaType 媒体类型
+ * @param params.title 视频标题 (可选)
+ * @param params.description 视频描述 (可选)
+ */
+export declare function sendMedia(params: {
+    agent: ResolvedAgentAccount;
+    toUser?: string;
+    toParty?: string;
+    toTag?: string;
+    chatId?: string;
+    mediaId: string;
+    mediaType: "image" | "voice" | "video" | "file";
+    title?: string;
+    description?: string;
+}): Promise<void>;
+/**
+ * **downloadMedia (下载媒体文件)**
+ *
+ * 通过 media_id 从企业微信服务器下载临时素材。
+ *
+ * @returns { buffer, contentType }
+ */
+export declare function downloadMedia(params: {
+    agent: ResolvedAgentAccount;
+    mediaId: string;
+    maxBytes?: number;
+}): Promise<{
+    buffer: Buffer;
+    contentType: string;
+    filename?: string;
+}>;

package/dist/src/agent/api-client.js

@@ -0,0 +1,292 @@
+/**
+ * WeCom Agent API 客户端
+ * 管理 AccessToken 缓存和 API 调用
+ */
+import crypto from "node:crypto";
+import { API_ENDPOINTS, LIMITS } from "../types/constants.js";
+import { readResponseBodyAsBuffer, wecomFetch } from "../http.js";
+function resolveWecomEgressProxyUrlFromNetwork(network) {
+    return network?.egressProxyUrl;
+}
+const tokenCaches = new Map();
+function normalizeUploadFilename(filename) {
+    const trimmed = filename.trim();
+    if (!trimmed)
+        return "file.bin";
+    const ext = trimmed.includes(".") ? `.${trimmed.split(".").pop().toLowerCase()}` : "";
+    const base = ext ? trimmed.slice(0, -ext.length) : trimmed;
+    const sanitizedBase = base
+        .replace(/[^\x20-\x7e]/g, "_")
+        .replace(/["\\\/;=]/g, "_")
+        .replace(/\s+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    const safeBase = sanitizedBase || "file";
+    const safeExt = ext.replace(/[^a-z0-9.]/g, "");
+    return `${safeBase}${safeExt || ".bin"}`;
+}
+function guessUploadContentType(filename) {
+    const ext = filename.split(".").pop()?.toLowerCase() || "";
+    const contentTypeMap = {
+        // image
+        jpg: "image/jpg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif", webp: "image/webp", bmp: "image/bmp",
+        // audio / video
+        amr: "voice/amr", mp3: "audio/mpeg", wav: "audio/wav", m4a: "audio/mp4", ogg: "audio/ogg", mp4: "video/mp4", mov: "video/quicktime",
+        // documents
+        txt: "text/plain", md: "text/markdown", csv: "text/csv", tsv: "text/tab-separated-values", json: "application/json",
+        xml: "application/xml", yaml: "application/yaml", yml: "application/yaml",
+        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",
+        ppt: "application/vnd.ms-powerpoint", pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        rtf: "application/rtf", odt: "application/vnd.oasis.opendocument.text",
+        // archives
+        zip: "application/zip", rar: "application/vnd.rar", "7z": "application/x-7z-compressed",
+        gz: "application/gzip", tgz: "application/gzip", tar: "application/x-tar",
+    };
+    return contentTypeMap[ext] || "application/octet-stream";
+}
+function requireAgentId(agent) {
+    if (typeof agent.agentId === "number" && Number.isFinite(agent.agentId))
+        return agent.agentId;
+    throw new Error(`wecom agent account=${agent.accountId} missing agentId; sending via cgi-bin/message/send requires agentId`);
+}
+/**
+ * **getAccessToken (获取 AccessToken)**
+ *
+ * 获取企业微信 API 调用所需的 AccessToken。
+ * 具备自动缓存和过期刷新机制。
+ *
+ * @param agent Agent 账号信息
+ * @returns 有效的 AccessToken
+ */
+export async function getAccessToken(agent) {
+    const cacheKey = `${agent.corpId}:${String(agent.agentId ?? "na")}`;
+    let cache = tokenCaches.get(cacheKey);
+    if (!cache) {
+        cache = { token: "", expiresAt: 0, refreshPromise: null };
+        tokenCaches.set(cacheKey, cache);
+    }
+    const now = Date.now();
+    if (cache.token && cache.expiresAt > now + LIMITS.TOKEN_REFRESH_BUFFER_MS) {
+        return cache.token;
+    }
+    // 防止并发刷新
+    if (cache.refreshPromise) {
+        return cache.refreshPromise;
+    }
+    cache.refreshPromise = (async () => {
+        try {
+            const url = `${API_ENDPOINTS.GET_TOKEN}?corpid=${encodeURIComponent(agent.corpId)}&corpsecret=${encodeURIComponent(agent.corpSecret)}`;
+            const res = await wecomFetch(url, undefined, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+            const json = await res.json();
+            if (!json?.access_token) {
+                throw new Error(`gettoken failed: ${json?.errcode} ${json?.errmsg}`);
+            }
+            cache.token = json.access_token;
+            cache.expiresAt = Date.now() + (json.expires_in ?? 7200) * 1000;
+            return cache.token;
+        }
+        finally {
+            cache.refreshPromise = null;
+        }
+    })();
+    return cache.refreshPromise;
+}
+/**
+ * **sendText (发送文本消息)**
+ *
+ * 调用 `message/send` (Agent) 或 `appchat/send` (群聊) 发送文本。
+ *
+ * @param params.agent 发送方 Agent
+ * @param params.toUser 接收用户 ID (单聊可选，可与 toParty/toTag 同时使用)
+ * @param params.toParty 接收部门 ID (单聊可选)
+ * @param params.toTag 接收标签 ID (单聊可选)
+ * @param params.chatId 接收群 ID (群聊模式必填，互斥)
+ * @param params.text 消息内容
+ */
+export async function sendText(params) {
+    const { agent, toUser, toParty, toTag, chatId, text } = params;
+    const token = await getAccessToken(agent);
+    const useChat = Boolean(chatId);
+    const url = useChat
+        ? `${API_ENDPOINTS.SEND_APPCHAT}?access_token=${encodeURIComponent(token)}`
+        : `${API_ENDPOINTS.SEND_MESSAGE}?access_token=${encodeURIComponent(token)}`;
+    const body = useChat
+        ? { chatid: chatId, msgtype: "text", text: { content: text } }
+        : {
+            touser: toUser,
+            toparty: toParty,
+            totag: toTag,
+            msgtype: "text",
+            agentid: requireAgentId(agent),
+            text: { content: text }
+        };
+    const res = await wecomFetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    }, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+    const json = await res.json();
+    if (json?.errcode !== 0) {
+        throw new Error(`send failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+    if (json?.invaliduser || json?.invalidparty || json?.invalidtag) {
+        const details = [
+            json.invaliduser ? `invaliduser=${json.invaliduser}` : "",
+            json.invalidparty ? `invalidparty=${json.invalidparty}` : "",
+            json.invalidtag ? `invalidtag=${json.invalidtag}` : ""
+        ].filter(Boolean).join(", ");
+        throw new Error(`send partial failure: ${details}`);
+    }
+}
+/**
+ * **uploadMedia (上传媒体文件)**
+ *
+ * 上传临时素材到企业微信。
+ * 素材有效期为 3 天。
+ *
+ * @param params.type 媒体类型 (image, voice, video, file)
+ * @param params.buffer 文件二进制数据
+ * @param params.filename 文件名 (需包含正确扩展名)
+ * @returns 媒体 ID (media_id)
+ */
+export async function uploadMedia(params) {
+    const { agent, type, buffer, filename } = params;
+    const safeFilename = normalizeUploadFilename(filename);
+    const token = await getAccessToken(agent);
+    const proxyUrl = resolveWecomEgressProxyUrlFromNetwork(agent.network);
+    // 添加 debug=1 参数获取更多错误信息
+    const url = `${API_ENDPOINTS.UPLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&type=${encodeURIComponent(type)}&debug=1`;
+    // DEBUG: 输出上传信息
+    console.log(`[wecom-upload] Uploading media: type=${type}, filename=${safeFilename}, size=${buffer.length} bytes`);
+    const uploadOnce = async (fileContentType) => {
+        // 手动构造 multipart/form-data 请求体
+        // 企业微信要求包含 filename 和 filelength
+        const boundary = `----WebKitFormBoundary${crypto.randomBytes(16).toString("hex")}`;
+        const header = Buffer.from(`--${boundary}\r\n` +
+            `Content-Disposition: form-data; name="media"; filename="${safeFilename}"; filelength=${buffer.length}\r\n` +
+            `Content-Type: ${fileContentType}\r\n\r\n`);
+        const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
+        const body = Buffer.concat([header, buffer, footer]);
+        console.log(`[wecom-upload] Multipart body size=${body.length}, boundary=${boundary}, fileContentType=${fileContentType}`);
+        const res = await wecomFetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": `multipart/form-data; boundary=${boundary}`,
+                "Content-Length": String(body.length),
+            },
+            body: body,
+        }, { proxyUrl, timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+        const json = await res.json();
+        console.log(`[wecom-upload] Response:`, JSON.stringify(json));
+        return json;
+    };
+    const preferredContentType = guessUploadContentType(safeFilename);
+    let json = await uploadOnce(preferredContentType);
+    // 某些文件类型在严格网关/企业微信校验下可能失败，回退到通用类型再试一次。
+    if (!json?.media_id && preferredContentType !== "application/octet-stream") {
+        console.warn(`[wecom-upload] Upload failed with ${preferredContentType}, retrying as application/octet-stream: ${json?.errcode} ${json?.errmsg}`);
+        json = await uploadOnce("application/octet-stream");
+    }
+    if (!json?.media_id) {
+        throw new Error(`upload failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+    return json.media_id;
+}
+/**
+ * **sendMedia (发送媒体消息)**
+ *
+ * 发送图片、音频、视频或文件。需先通过 `uploadMedia` 获取 media_id。
+ *
+ * @param params.agent 发送方 Agent
+ * @param params.toUser 接收用户 ID (单聊可选)
+ * @param params.toParty 接收部门 ID (单聊可选)
+ * @param params.toTag 接收标签 ID (单聊可选)
+ * @param params.chatId 接收群 ID (群聊模式必填)
+ * @param params.mediaId 媒体 ID
+ * @param params.mediaType 媒体类型
+ * @param params.title 视频标题 (可选)
+ * @param params.description 视频描述 (可选)
+ */
+export async function sendMedia(params) {
+    const { agent, toUser, toParty, toTag, chatId, mediaId, mediaType, title, description } = params;
+    const token = await getAccessToken(agent);
+    const useChat = Boolean(chatId);
+    const url = useChat
+        ? `${API_ENDPOINTS.SEND_APPCHAT}?access_token=${encodeURIComponent(token)}`
+        : `${API_ENDPOINTS.SEND_MESSAGE}?access_token=${encodeURIComponent(token)}`;
+    const mediaPayload = mediaType === "video"
+        ? { media_id: mediaId, title: title ?? "Video", description: description ?? "" }
+        : { media_id: mediaId };
+    const body = useChat
+        ? { chatid: chatId, msgtype: mediaType, [mediaType]: mediaPayload }
+        : {
+            touser: toUser,
+            toparty: toParty,
+            totag: toTag,
+            msgtype: mediaType,
+            agentid: requireAgentId(agent),
+            [mediaType]: mediaPayload
+        };
+    const res = await wecomFetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    }, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+    const json = await res.json();
+    if (json?.errcode !== 0) {
+        throw new Error(`send ${mediaType} failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+    if (json?.invaliduser || json?.invalidparty || json?.invalidtag) {
+        const details = [
+            json.invaliduser ? `invaliduser=${json.invaliduser}` : "",
+            json.invalidparty ? `invalidparty=${json.invalidparty}` : "",
+            json.invalidtag ? `invalidtag=${json.invalidtag}` : ""
+        ].filter(Boolean).join(", ");
+        throw new Error(`send ${mediaType} partial failure: ${details}`);
+    }
+}
+/**
+ * **downloadMedia (下载媒体文件)**
+ *
+ * 通过 media_id 从企业微信服务器下载临时素材。
+ *
+ * @returns { buffer, contentType }
+ */
+export async function downloadMedia(params) {
+    const { agent, mediaId } = params;
+    const token = await getAccessToken(agent);
+    const url = `${API_ENDPOINTS.DOWNLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&media_id=${encodeURIComponent(mediaId)}`;
+    const res = await wecomFetch(url, undefined, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+    if (!res.ok) {
+        throw new Error(`download failed: ${res.status}`);
+    }
+    const contentType = res.headers.get("content-type") || "application/octet-stream";
+    const disposition = res.headers.get("content-disposition") || "";
+    const filename = (() => {
+        // 兼容：filename="a.md" / filename=a.md / filename*=UTF-8''a%2Eb.md
+        const mStar = disposition.match(/filename\*\s*=\s*([^;]+)/i);
+        if (mStar) {
+            const raw = mStar[1].trim().replace(/^"(.*)"$/, "$1");
+            const parts = raw.split("''");
+            const encoded = parts.length === 2 ? parts[1] : raw;
+            try {
+                return decodeURIComponent(encoded);
+            }
+            catch {
+                return encoded;
+            }
+        }
+        const m = disposition.match(/filename\s*=\s*([^;]+)/i);
+        if (!m)
+            return undefined;
+        return m[1].trim().replace(/^"(.*)"$/, "$1") || undefined;
+    })();
+    // 检查是否返回了错误 JSON
+    if (contentType.includes("application/json")) {
+        const json = await res.json();
+        throw new Error(`download failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+    const buffer = await readResponseBodyAsBuffer(res, params.maxBytes);
+    return { buffer, contentType, filename };
+}

package/dist/src/agent/handler.d.ts

@@ -0,0 +1,63 @@
+/**
+ * WeCom Agent Webhook 处理器
+ * 处理 XML 格式回调
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
+import type { ResolvedAgentAccount } from "../types/index.js";
+import type { WecomAgentInboundMessage } from "../types/index.js";
+/**
+ * **AgentWebhookParams (Webhook 处理器参数)**
+ *
+ * 传递给 Agent Webhook 处理函数的上下文参数集合。
+ * @property req Node.js 原始请求对象
+ * @property res Node.js 原始响应对象
+ * @property agent 解析后的 Agent 账号信息
+ * @property config 全局插件配置
+ * @property core OpenClaw 插件运行时
+ * @property log 可选日志输出函数
+ * @property error 可选错误输出函数
+ */
+export type AgentWebhookParams = {
+    req: IncomingMessage;
+    res: ServerResponse;
+    /**
+     * 上游已完成验签/解密时传入，避免重复协议处理。
+     * 仅用于 POST 消息回调流程。
+     */
+    verifiedPost?: {
+        timestamp: string;
+        nonce: string;
+        signature: string;
+        encrypted: string;
+        decrypted: string;
+        parsed: WecomAgentInboundMessage;
+    };
+    agent: ResolvedAgentAccount;
+    config: OpenClawConfig;
+    core: PluginRuntime;
+    log?: (msg: string) => void;
+    error?: (msg: string) => void;
+};
+export type AgentInboundProcessDecision = {
+    shouldProcess: boolean;
+    reason: string;
+};
+/**
+ * 仅允许“用户意图消息”进入 AI 会话。
+ * - event 回调（如 enter_agent/subscribe）不应触发会话与自动回复
+ * - 系统发送者（sys）不应触发会话与自动回复
+ * - 缺失发送者时默认丢弃，避免写入异常会话
+ */
+export declare function shouldProcessAgentInboundMessage(params: {
+    msgType: string;
+    fromUser: string;
+    eventType?: string;
+}): AgentInboundProcessDecision;
+/**
+ * **handleAgentWebhook (Agent Webhook 入口)**
+ *
+ * 统一处理 Agent 模式的 POST 消息回调请求。
+ * URL 验证与验签/解密由 monitor 层统一处理后再调用本函数。
+ */
+export declare function handleAgentWebhook(params: AgentWebhookParams): Promise<boolean>;