@mocrane/wecom 2026.2.5

package/src/agent/handler.ts

@@ -0,0 +1,566 @@
+/**
+ * WeCom Agent Webhook 处理器
+ * 处理 XML 格式回调
+ */
+
+import { pathToFileURL } from "node:url";
+import path from "node:path";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
+import type { ResolvedAgentAccount } from "../types/index.js";
+import { LIMITS } from "../types/constants.js";
+import { decryptWecomEncrypted, verifyWecomSignature, computeWecomMsgSignature, encryptWecomPlaintext } from "../crypto/index.js";
+import { extractEncryptFromXml, buildEncryptedXmlResponse } from "../crypto/xml.js";
+import { parseXml, extractMsgType, extractFromUser, extractContent, extractChatId, extractMediaId, extractMsgId, extractFileName } from "../shared/xml-parser.js";
+import { sendText, downloadMedia } from "./api-client.js";
+import { getWecomRuntime } from "../runtime.js";
+import type { WecomAgentInboundMessage } from "../types/index.js";
+import { buildWecomUnauthorizedCommandPrompt, resolveWecomCommandAuthorization } from "../shared/command-auth.js";
+import { resolveWecomMediaMaxBytes } from "../config/index.js";
+
+/** 错误提示信息 */
+const ERROR_HELP = "";
+
+// Agent webhook 幂等去重池（防止企微回调重试导致重复回复）
+// 注意：这是进程内内存去重，重启会清空；但足以覆盖企微的短周期重试。
+const RECENT_MSGID_TTL_MS = 10 * 60 * 1000;
+const recentAgentMsgIds = new Map<string, number>();
+
+function rememberAgentMsgId(msgId: string): boolean {
+    const now = Date.now();
+    const existing = recentAgentMsgIds.get(msgId);
+    if (existing && now - existing < RECENT_MSGID_TTL_MS) return false;
+    recentAgentMsgIds.set(msgId, now);
+    // 简单清理：只在写入时做一次线性 prune，避免无界增长
+    for (const [k, ts] of recentAgentMsgIds) {
+        if (now - ts >= RECENT_MSGID_TTL_MS) recentAgentMsgIds.delete(k);
+    }
+    return true;
+}
+
+function looksLikeTextFile(buffer: Buffer): boolean {
+    const sampleSize = Math.min(buffer.length, 4096);
+    if (sampleSize === 0) return true;
+    let bad = 0;
+    for (let i = 0; i < sampleSize; i++) {
+        const b = buffer[i]!;
+        const isWhitespace = b === 0x09 || b === 0x0a || b === 0x0d; // \t \n \r
+        const isPrintable = b >= 0x20 && b !== 0x7f;
+        if (!isWhitespace && !isPrintable) bad++;
+    }
+    // 非可打印字符占比太高，基本可判断为二进制
+    return bad / sampleSize <= 0.02;
+}
+
+function analyzeTextHeuristic(buffer: Buffer): { sampleSize: number; badCount: number; badRatio: number } {
+    const sampleSize = Math.min(buffer.length, 4096);
+    if (sampleSize === 0) return { sampleSize: 0, badCount: 0, badRatio: 0 };
+    let badCount = 0;
+    for (let i = 0; i < sampleSize; i++) {
+        const b = buffer[i]!;
+        const isWhitespace = b === 0x09 || b === 0x0a || b === 0x0d;
+        const isPrintable = b >= 0x20 && b !== 0x7f;
+        if (!isWhitespace && !isPrintable) badCount++;
+    }
+    return { sampleSize, badCount, badRatio: badCount / sampleSize };
+}
+
+function previewHex(buffer: Buffer, maxBytes = 32): string {
+    const n = Math.min(buffer.length, maxBytes);
+    if (n <= 0) return "";
+    return buffer
+        .subarray(0, n)
+        .toString("hex")
+        .replace(/(..)/g, "$1 ")
+        .trim();
+}
+
+function buildTextFilePreview(buffer: Buffer, maxChars: number): string | undefined {
+    if (!looksLikeTextFile(buffer)) return undefined;
+    const text = buffer.toString("utf8");
+    if (!text.trim()) return undefined;
+    const truncated = text.length > maxChars ? `${text.slice(0, maxChars)}\n…(已截断)` : text;
+    return truncated;
+}
+
+/**
+ * **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;
+    agent: ResolvedAgentAccount;
+    config: OpenClawConfig;
+    core: PluginRuntime;
+    log?: (msg: string) => void;
+    error?: (msg: string) => void;
+};
+
+/**
+ * **resolveQueryParams (解析查询参数)**
+ * 
+ * 辅助函数：从 IncomingMessage 中解析 URL 查询字符串，用于获取签名、时间戳等参数。
+ */
+function resolveQueryParams(req: IncomingMessage): URLSearchParams {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    return url.searchParams;
+}
+
+/**
+ * **readRawBody (读取原始请求体)**
+ * 
+ * 异步读取 HTTP POST 请求的原始 BODY 数据（XML 字符串）。
+ * 包含最大体积限制检查，防止内存溢出攻击。
+ */
+async function readRawBody(req: IncomingMessage, maxSize: number = LIMITS.MAX_REQUEST_BODY_SIZE): Promise<string> {
+    return new Promise((resolve, reject) => {
+        const chunks: Buffer[] = [];
+        let size = 0;
+
+        req.on("data", (chunk: Buffer) => {
+            size += chunk.length;
+            if (size > maxSize) {
+                reject(new Error("Request body too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+
+        req.on("end", () => {
+            resolve(Buffer.concat(chunks).toString("utf8"));
+        });
+
+        req.on("error", reject);
+    });
+}
+
+/**
+ * **handleUrlVerification (处理 URL 验证)**
+ * 
+ * 处理企业微信 Agent 配置时的 GET 请求验证。
+ * 流程：
+ * 1. 验证 msg_signature 签名。
+ * 2. 解密 echostr 参数。
+ * 3. 返回解密后的明文 echostr。
+ */
+async function handleUrlVerification(
+    req: IncomingMessage,
+    res: ServerResponse,
+    agent: ResolvedAgentAccount,
+): Promise<boolean> {
+    const query = resolveQueryParams(req);
+    const timestamp = query.get("timestamp") ?? "";
+    const nonce = query.get("nonce") ?? "";
+    const echostr = query.get("echostr") ?? "";
+    const signature = query.get("msg_signature") ?? "";
+    const remote = req.socket?.remoteAddress ?? "unknown";
+
+    // 不输出敏感参数内容，仅输出存在性
+    // 用于排查：是否有请求打到 /wecom/agent
+    // 以及是否带齐 timestamp/nonce/msg_signature/echostr
+    // eslint-disable-next-line no-unused-vars
+    const _debug = { remote, hasTimestamp: Boolean(timestamp), hasNonce: Boolean(nonce), hasSig: Boolean(signature), hasEchostr: Boolean(echostr) };
+
+    const valid = verifyWecomSignature({
+        token: agent.token,
+        timestamp,
+        nonce,
+        encrypt: echostr,
+        signature,
+    });
+
+    if (!valid) {
+        res.statusCode = 401;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end(`unauthorized - 签名验证失败，请检查 Token 配置${ERROR_HELP}`);
+        return true;
+    }
+
+    try {
+        const plain = decryptWecomEncrypted({
+            encodingAESKey: agent.encodingAESKey,
+            receiveId: agent.corpId,
+            encrypt: echostr,
+        });
+        res.statusCode = 200;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end(plain);
+        return true;
+    } catch {
+        res.statusCode = 400;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end(`decrypt failed - 解密失败，请检查 EncodingAESKey 配置${ERROR_HELP}`);
+        return true;
+    }
+}
+
+/**
+ * 处理消息回调 (POST)
+ */
+async function handleMessageCallback(params: AgentWebhookParams): Promise<boolean> {
+    const { req, res, agent, config, core, log, error } = params;
+
+    try {
+        log?.(`[wecom-agent] inbound: method=${req.method ?? "UNKNOWN"} remote=${req.socket?.remoteAddress ?? "unknown"}`);
+        const rawXml = await readRawBody(req);
+        log?.(`[wecom-agent] inbound: rawXmlBytes=${Buffer.byteLength(rawXml, "utf8")}`);
+        const encrypted = extractEncryptFromXml(rawXml);
+        log?.(`[wecom-agent] inbound: hasEncrypt=${Boolean(encrypted)} encryptLen=${encrypted ? String(encrypted).length : 0}`);
+
+        const query = resolveQueryParams(req);
+        const timestamp = query.get("timestamp") ?? "";
+        const nonce = query.get("nonce") ?? "";
+        const signature = query.get("msg_signature") ?? "";
+        log?.(
+            `[wecom-agent] inbound: query timestamp=${timestamp ? "yes" : "no"} nonce=${nonce ? "yes" : "no"} msg_signature=${signature ? "yes" : "no"}`,
+        );
+
+        // 验证签名
+        const valid = verifyWecomSignature({
+            token: agent.token,
+            timestamp,
+            nonce,
+            encrypt: encrypted,
+            signature,
+        });
+
+        if (!valid) {
+            error?.(`[wecom-agent] inbound: signature invalid`);
+            res.statusCode = 401;
+            res.setHeader("Content-Type", "text/plain; charset=utf-8");
+            res.end(`unauthorized - 签名验证失败${ERROR_HELP}`);
+            return true;
+        }
+
+        // 解密
+        const decrypted = decryptWecomEncrypted({
+            encodingAESKey: agent.encodingAESKey,
+            receiveId: agent.corpId,
+            encrypt: encrypted,
+        });
+        log?.(`[wecom-agent] inbound: decryptedBytes=${Buffer.byteLength(decrypted, "utf8")}`);
+
+        // 解析 XML
+        const msg = parseXml(decrypted);
+        const msgType = extractMsgType(msg);
+        const fromUser = extractFromUser(msg);
+        const chatId = extractChatId(msg);
+        const msgId = extractMsgId(msg);
+        if (msgId) {
+            const ok = rememberAgentMsgId(msgId);
+            if (!ok) {
+                log?.(`[wecom-agent] duplicate msgId=${msgId} from=${fromUser} chatId=${chatId ?? "N/A"} type=${msgType}; skipped`);
+                res.statusCode = 200;
+                res.setHeader("Content-Type", "text/plain; charset=utf-8");
+                res.end("success");
+                return true;
+            }
+        }
+        const content = String(extractContent(msg) ?? "");
+
+        const preview = content.length > 100 ? `${content.slice(0, 100)}…` : content;
+        log?.(`[wecom-agent] ${msgType} from=${fromUser} chatId=${chatId ?? "N/A"} msgId=${msgId ?? "N/A"} content=${preview}`);
+
+        // 先返回 success (Agent 模式使用 API 发送回复，不用被动回复)
+        res.statusCode = 200;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end("success");
+
+        // 异步处理消息
+        processAgentMessage({
+            agent,
+            config,
+            core,
+            fromUser,
+            chatId,
+            msgType,
+            content,
+            msg,
+            log,
+            error,
+        }).catch((err) => {
+            error?.(`[wecom-agent] process failed: ${String(err)}`);
+        });
+
+        return true;
+    } catch (err) {
+        error?.(`[wecom-agent] callback failed: ${String(err)}`);
+        res.statusCode = 400;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end(`error - 回调处理失败${ERROR_HELP}`);
+        return true;
+    }
+}
+
+/**
+ * **processAgentMessage (处理 Agent 消息)**
+ * 
+ * 异步处理解密后的消息内容，并触发 OpenClaw Agent。
+ * 流程：
+ * 1. 路由解析：根据 userid或群ID 确定 Agent 路由。
+ * 2. 媒体处理：如果是图片/文件等，下载资源。
+ * 3. 上下文构建：创建 Inbound Context。
+ * 4. 会话记录：更新 Session 状态。
+ * 5. 调度回复：将 Agent 的响应通过 `api-client` 发送回企业微信。
+ */
+async function processAgentMessage(params: {
+    agent: ResolvedAgentAccount;
+    config: OpenClawConfig;
+    core: PluginRuntime;
+    fromUser: string;
+    chatId?: string;
+    msgType: string;
+    content: string;
+    msg: WecomAgentInboundMessage;
+    log?: (msg: string) => void;
+    error?: (msg: string) => void;
+}): Promise<void> {
+    const { agent, config, core, fromUser, chatId, content, msg, msgType, log, error } = params;
+
+    const isGroup = Boolean(chatId);
+    const peerId = isGroup ? chatId! : fromUser;
+    const mediaMaxBytes = resolveWecomMediaMaxBytes(config);
+
+    // 处理媒体文件
+    const attachments: any[] = []; // TODO: define specific type
+    let finalContent = content;
+    let mediaPath: string | undefined;
+    let mediaType: string | undefined;
+
+    if (["image", "voice", "video", "file"].includes(msgType)) {
+        const mediaId = extractMediaId(msg);
+        if (mediaId) {
+            try {
+                log?.(`[wecom-agent] downloading media: ${mediaId} (${msgType})`);
+                const { buffer, contentType, filename: headerFileName } = await downloadMedia({ agent, mediaId, maxBytes: mediaMaxBytes });
+                const xmlFileName = extractFileName(msg);
+                const originalFileName = (xmlFileName || headerFileName || `${mediaId}.bin`).trim();
+                const heuristic = analyzeTextHeuristic(buffer);
+
+                // 推断文件名后缀
+                const extMap: Record<string, string> = {
+                    "image/jpeg": "jpg", "image/png": "png", "image/gif": "gif",
+                    "audio/amr": "amr", "audio/speex": "speex", "video/mp4": "mp4",
+                };
+                const textPreview = msgType === "file" ? buildTextFilePreview(buffer, 12_000) : undefined;
+                const looksText = Boolean(textPreview);
+                const originalExt = path.extname(originalFileName).toLowerCase();
+                const normalizedContentType =
+                    looksText && originalExt === ".md" ? "text/markdown" :
+                    looksText && (!contentType || contentType === "application/octet-stream")
+                        ? "text/plain; charset=utf-8"
+                        : contentType;
+
+                const ext = extMap[normalizedContentType] || (looksText ? "txt" : "bin");
+                const filename = `${mediaId}.${ext}`;
+
+                log?.(
+                    `[wecom-agent] file meta: msgType=${msgType} mediaId=${mediaId} size=${buffer.length} maxBytes=${mediaMaxBytes} ` +
+                    `contentType=${contentType} normalizedContentType=${normalizedContentType} originalFileName=${originalFileName} ` +
+                    `xmlFileName=${xmlFileName ?? "N/A"} headerFileName=${headerFileName ?? "N/A"} ` +
+                    `textHeuristic(sample=${heuristic.sampleSize}, bad=${heuristic.badCount}, ratio=${heuristic.badRatio.toFixed(4)}) ` +
+                    `headHex="${previewHex(buffer)}"`,
+                );
+
+                // 使用 Core SDK 保存媒体文件
+                const saved = await core.channel.media.saveMediaBuffer(
+                    buffer,
+                    normalizedContentType,
+                    "inbound", // context/scope
+                    mediaMaxBytes, // limit
+                    originalFileName
+                );
+
+                log?.(`[wecom-agent] media saved to: ${saved.path}`);
+                mediaPath = saved.path;
+                mediaType = normalizedContentType;
+
+                // 构建附件
+                attachments.push({
+                    name: originalFileName,
+                    mimeType: normalizedContentType,
+                    url: pathToFileURL(saved.path).href, // 使用跨平台安全的文件 URL
+                });
+
+                // 更新文本提示
+                if (textPreview) {
+                    finalContent = [
+                        content,
+                        "",
+                        "文件内容预览：",
+                        "```",
+                        textPreview,
+                        "```",
+                        `(已下载 ${buffer.length} 字节)`,
+                    ].join("\n");
+                } else {
+                    if (msgType === "file") {
+                        finalContent = [
+                            content,
+                            "",
+                            `已收到文件：${originalFileName}`,
+                            `文件类型：${normalizedContentType || contentType || "未知"}`,
+                            "提示：当前仅对文本/Markdown/JSON/CSV/HTML/PDF（可选）做内容抽取；其他二进制格式请转为 PDF 或复制文本内容。",
+                            `(已下载 ${buffer.length} 字节)`,
+                        ].join("\n");
+                    } else {
+                        finalContent = `${content} (已下载 ${buffer.length} 字节)`;
+                    }
+                }
+                log?.(`[wecom-agent] file preview: enabled=${looksText} finalContentLen=${finalContent.length} attachments=${attachments.length}`);
+            } catch (err) {
+                error?.(`[wecom-agent] media processing failed: ${String(err)}`);
+                finalContent = [
+                    content,
+                    "",
+                    `媒体处理失败：${String(err)}`,
+                    `提示：可在 OpenClaw 配置中提高 channels.wecom.media.maxBytes（当前=${mediaMaxBytes}）`,
+                    `例如：openclaw config set channels.wecom.media.maxBytes ${50 * 1024 * 1024}`,
+                ].join("\n");
+            }
+        } else {
+            const keys = Object.keys((msg as unknown as Record<string, unknown>) ?? {}).slice(0, 50).join(",");
+            error?.(`[wecom-agent] mediaId not found for ${msgType}; keys=${keys}`);
+        }
+    }
+
+    // 解析路由
+    const route = core.channel.routing.resolveAgentRoute({
+        cfg: config,
+        channel: "wecom",
+        accountId: agent.accountId,
+        peer: { kind: isGroup ? "group" : "dm", id: peerId },
+    });
+
+    // 构建上下文
+    const fromLabel = isGroup ? `group:${peerId}` : `user:${fromUser}`;
+    const storePath = core.channel.session.resolveStorePath(config.session?.store, {
+        agentId: route.agentId,
+    });
+    const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(config);
+    const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+        storePath,
+        sessionKey: route.sessionKey,
+    });
+    const body = core.channel.reply.formatAgentEnvelope({
+        channel: "WeCom",
+        from: fromLabel,
+        previousTimestamp,
+        envelope: envelopeOptions,
+        body: finalContent,
+    });
+
+    const authz = await resolveWecomCommandAuthorization({
+        core,
+        cfg: config,
+        // Agent 门禁应读取 channels.wecom.agent.dm（即 agent.config.dm），而不是 channels.wecom.dm（不存在）
+        accountConfig: agent.config as any,
+        rawBody: finalContent,
+        senderUserId: fromUser,
+    });
+    log?.(`[wecom-agent] authz: dmPolicy=${authz.dmPolicy} shouldCompute=${authz.shouldComputeAuth} sender=${fromUser.toLowerCase()} senderAllowed=${authz.senderAllowed} authorizerConfigured=${authz.authorizerConfigured} commandAuthorized=${String(authz.commandAuthorized)}`);
+
+    // 命令门禁：未授权时必须明确回复（Agent 侧用私信提示）
+    if (authz.shouldComputeAuth && authz.commandAuthorized !== true) {
+        const prompt = buildWecomUnauthorizedCommandPrompt({ senderUserId: fromUser, dmPolicy: authz.dmPolicy, scope: "agent" });
+        try {
+            await sendText({ agent, toUser: fromUser, chatId: undefined, text: prompt });
+            log?.(`[wecom-agent] unauthorized command: replied via DM to ${fromUser}`);
+        } catch (err: unknown) {
+            error?.(`[wecom-agent] unauthorized command reply failed: ${String(err)}`);
+        }
+        return;
+    }
+
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+        Body: body,
+        RawBody: finalContent,
+        CommandBody: finalContent,
+        Attachments: attachments.length > 0 ? attachments : undefined,
+        From: isGroup ? `wecom:group:${peerId}` : `wecom:${fromUser}`,
+        To: `wecom:${peerId}`,
+        SessionKey: route.sessionKey,
+        AccountId: route.accountId,
+        ChatType: isGroup ? "group" : "direct",
+        ConversationLabel: fromLabel,
+        SenderName: fromUser,
+        SenderId: fromUser,
+        Provider: "wecom",
+        Surface: "wecom",
+        OriginatingChannel: "wecom",
+        // 标记为 Agent 会话的回复路由目标，避免与 Bot 会话混淆：
+        // - 用于让 /new /reset 这类命令回执不被 Bot 侧策略拦截
+        // - 群聊场景也统一路由为私信触发者（与 deliver 策略一致）
+        OriginatingTo: `wecom-agent:${fromUser}`,
+        CommandAuthorized: authz.commandAuthorized ?? true,
+        MediaPath: mediaPath,
+        MediaType: mediaType,
+        MediaUrl: mediaPath,
+    });
+
+    // 记录会话
+    await core.channel.session.recordInboundSession({
+        storePath,
+        sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+        ctx: ctxPayload,
+        onRecordError: (err: unknown) => {
+            error?.(`[wecom-agent] session record failed: ${String(err)}`);
+        },
+    });
+
+    // 调度回复
+    await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+        ctx: ctxPayload,
+        cfg: config,
+        dispatcherOptions: {
+            deliver: async (payload: { text?: string }, info: { kind: string }) => {
+                const text = payload.text ?? "";
+                if (!text) return;
+
+                try {
+                    // 统一策略：Agent 模式在群聊场景默认只私信触发者（避免 wr/wc chatId 86008）
+                    await sendText({ agent, toUser: fromUser, chatId: undefined, text });
+                    log?.(`[wecom-agent] reply delivered (${info.kind}) to ${fromUser}`);
+                } catch (err: unknown) {
+                    error?.(`[wecom-agent] reply failed: ${String(err)}`);
+                }
+            },
+            onError: (err: unknown, info: { kind: string }) => {
+                error?.(`[wecom-agent] ${info.kind} reply error: ${String(err)}`);
+            },
+        },
+        replyOptions: {
+            disableBlockStreaming: true,
+        },
+    });
+}
+
+/**
+ * **handleAgentWebhook (Agent Webhook 入口)**
+ * 
+ * 统一处理 Agent 模式的 Webhook 请求。
+ * 根据 HTTP 方法分发到 URL 验证 (GET) 或 消息处理 (POST)。
+ */
+export async function handleAgentWebhook(params: AgentWebhookParams): Promise<boolean> {
+    const { req } = params;
+
+    if (req.method === "GET") {
+        return handleUrlVerification(req, params.res, params.agent);
+    }
+
+    if (req.method === "POST") {
+        return handleMessageCallback(params);
+    }
+
+    return false;
+}

package/src/agent/index.ts

@@ -0,0 +1,12 @@
+/**
+ * WeCom Agent 模块导出
+ */
+
+export { handleAgentWebhook, type AgentWebhookParams } from "./handler.js";
+export {
+    getAccessToken,
+    sendText,
+    uploadMedia,
+    sendMedia,
+    downloadMedia,
+} from "./api-client.js";