@wecom/wecom-openclaw-plugin 2026.4.2 → 2026.4.3-beta.0

package/dist/src/webhook/http.d.ts

@@ -0,0 +1,26 @@
+/**
+ * **WecomHttpOptions (HTTP 选项)**
+ *
+ * @property proxyUrl 代理服务器地址
+ * @property timeoutMs 请求超时时间 (毫秒)
+ * @property signal AbortSignal 信号
+ */
+export type WecomHttpOptions = {
+    proxyUrl?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+/**
+ * **wecomFetch (统一 HTTP 请求)**
+ *
+ * 基于 `undici` 的 fetch 封装，自动处理 ProxyAgent 和 Timeout。
+ * 所有对企业微信 API 的调用都应经过此函数。
+ */
+export declare function wecomFetch(input: string | URL, init?: RequestInit, opts?: WecomHttpOptions): Promise<Response>;
+/**
+ * **readResponseBodyAsBuffer (读取响应 Body)**
+ *
+ * 将 Response Body 读取为 Buffer，支持最大字节限制以防止内存溢出。
+ * 适用于下载媒体文件等场景。
+ */
+export declare function readResponseBodyAsBuffer(res: Response, maxBytes?: number): Promise<Buffer>;

package/dist/src/webhook/http.js

@@ -0,0 +1,94 @@
+import { ProxyAgent, fetch as undiciFetch } from "undici";
+const proxyDispatchers = new Map();
+/**
+ * **getProxyDispatcher (获取代理 Dispatcher)**
+ *
+ * 缓存并复用 ProxyAgent，避免重复创建连接池。
+ */
+function getProxyDispatcher(proxyUrl) {
+    const existing = proxyDispatchers.get(proxyUrl);
+    if (existing)
+        return existing;
+    const created = new ProxyAgent(proxyUrl);
+    proxyDispatchers.set(proxyUrl, created);
+    return created;
+}
+function mergeAbortSignal(params) {
+    const signals = [];
+    if (params.signal)
+        signals.push(params.signal);
+    if (params.timeoutMs && Number.isFinite(params.timeoutMs) && params.timeoutMs > 0) {
+        signals.push(AbortSignal.timeout(params.timeoutMs));
+    }
+    if (!signals.length)
+        return undefined;
+    if (signals.length === 1)
+        return signals[0];
+    return AbortSignal.any(signals);
+}
+/**
+ * **wecomFetch (统一 HTTP 请求)**
+ *
+ * 基于 `undici` 的 fetch 封装，自动处理 ProxyAgent 和 Timeout。
+ * 所有对企业微信 API 的调用都应经过此函数。
+ */
+export async function wecomFetch(input, init, opts) {
+    const proxyUrl = opts?.proxyUrl?.trim() ?? "";
+    const dispatcher = proxyUrl ? getProxyDispatcher(proxyUrl) : undefined;
+    const initSignal = init?.signal ?? undefined;
+    const signal = mergeAbortSignal({ signal: opts?.signal ?? initSignal, timeoutMs: opts?.timeoutMs });
+    const headers = new Headers(init?.headers ?? {});
+    if (!headers.has("User-Agent")) {
+        headers.set("User-Agent", "OpenClaw/2.0 (WeCom-Agent)");
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const nextInit = {
+        ...(init ?? {}),
+        ...(signal ? { signal } : {}),
+        ...(dispatcher ? { dispatcher } : {}),
+        headers,
+    };
+    try {
+        return await undiciFetch(input, nextInit);
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "TypeError" && err.message === "fetch failed") {
+            const cause = err.cause;
+            console.error(`[wecom-http] fetch failed: ${input} (proxy: ${proxyUrl || "none"})${cause ? ` - cause: ${String(cause)}` : ""}`);
+        }
+        throw err;
+    }
+}
+/**
+ * **readResponseBodyAsBuffer (读取响应 Body)**
+ *
+ * 将 Response Body 读取为 Buffer，支持最大字节限制以防止内存溢出。
+ * 适用于下载媒体文件等场景。
+ */
+export async function readResponseBodyAsBuffer(res, maxBytes) {
+    if (!res.body)
+        return Buffer.alloc(0);
+    const limit = maxBytes && Number.isFinite(maxBytes) && maxBytes > 0 ? maxBytes : undefined;
+    const chunks = [];
+    let total = 0;
+    const reader = res.body.getReader();
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (!value)
+            continue;
+        total += value.byteLength;
+        if (limit && total > limit) {
+            try {
+                await reader.cancel("body too large");
+            }
+            catch {
+                // ignore
+            }
+            throw new Error(`response body too large (>${limit} bytes)`);
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks.map((c) => Buffer.from(c)));
+}

package/dist/src/webhook/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Webhook 模块公共入口
+ *
+ * Re-export 所有 Webhook 模式对外暴露的函数和类型。
+ */
+export { handleWecomWebhookRequest } from "./handler.js";
+export { registerWecomWebhookTarget, getRegisteredTargets, getWebhookTargetsMap, hasActiveTargets, parseWebhookPath, } from "./target.js";
+export { startWebhookGateway, stopWebhookGateway, getMonitorState } from "./gateway.js";
+export type { WecomWebhookTarget, WebhookGatewayContext, ResolvedWebhookAccount, WebhookAccountConfig, WecomRuntimeEnv, StreamState, PendingInbound, ActiveReplyState, WebhookInboundMessage, } from "./types.js";
+export { STREAM_TTL_MS, ACTIVE_REPLY_TTL_MS, DEFAULT_DEBOUNCE_MS, STREAM_MAX_BYTES, BOT_WINDOW_MS, BOT_SWITCH_MARGIN_MS, REQUEST_TIMEOUT_MS, PRUNE_INTERVAL_MS, WEBHOOK_PATHS, } from "./types.js";
+export { monitorState, WebhookMonitorState } from "./state.js";

package/dist/src/webhook/index.js

@@ -0,0 +1,14 @@
+/**
+ * Webhook 模块公共入口
+ *
+ * Re-export 所有 Webhook 模式对外暴露的函数和类型。
+ */
+// ── Handler ─────────────────────────────────────────────────────────
+export { handleWecomWebhookRequest } from "./handler.js";
+// ── Target ──────────────────────────────────────────────────────────
+export { registerWecomWebhookTarget, getRegisteredTargets, getWebhookTargetsMap, hasActiveTargets, parseWebhookPath, } from "./target.js";
+// ── Gateway ─────────────────────────────────────────────────────────
+export { startWebhookGateway, stopWebhookGateway, getMonitorState } from "./gateway.js";
+export { STREAM_TTL_MS, ACTIVE_REPLY_TTL_MS, DEFAULT_DEBOUNCE_MS, STREAM_MAX_BYTES, BOT_WINDOW_MS, BOT_SWITCH_MARGIN_MS, REQUEST_TIMEOUT_MS, PRUNE_INTERVAL_MS, WEBHOOK_PATHS, } from "./types.js";
+// ── State (全局单例) ────────────────────────────────────────────────
+export { monitorState, WebhookMonitorState } from "./state.js";

package/dist/src/webhook/media.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Webhook 入站媒体处理
+ *
+ * 从 @mocrane/wecom media.ts 部分迁移（仅入站解密）。
+ * 负责：AES-CBC 解密企微加密媒体文件、MIME 类型检测。
+ */
+import { type WecomHttpOptions } from "./http.js";
+/** 企微使用 32 字节 PKCS#7 块大小（不是 AES 的 16 字节块） */
+export declare const WECOM_PKCS7_BLOCK_SIZE = 32;
+/** 解密后的媒体文件及源信息（对齐原版 DecryptedWecomMedia） */
+export type DecryptedWecomMedia = {
+    buffer: Buffer;
+    /** HTTP Content-Type（归一化后） */
+    sourceContentType?: string;
+    /** 从 Content-Disposition 提取的文件名 */
+    sourceFilename?: string;
+    /** 最终请求 URL（跟随重定向后） */
+    sourceUrl?: string;
+};
+/**
+ * **decryptWecomMediaWithMeta (解密企业微信媒体并返回源信息)**
+ *
+ * 在返回解密结果的同时，保留下载响应中的元信息（content-type / filename / final url），
+ * 供上层更准确地推断文件后缀和 MIME。
+ */
+export declare function decryptWecomMediaWithMeta(url: string, encodingAESKey: string, params?: {
+    maxBytes?: number;
+    http?: WecomHttpOptions;
+}): Promise<DecryptedWecomMedia>;

package/dist/src/webhook/media.js

@@ -0,0 +1,88 @@
+/**
+ * Webhook 入站媒体处理
+ *
+ * 从 @mocrane/wecom media.ts 部分迁移（仅入站解密）。
+ * 负责：AES-CBC 解密企微加密媒体文件、MIME 类型检测。
+ */
+import crypto from "node:crypto";
+import { pkcs7Unpad, decodeEncodingAESKey } from "@wecom/aibot-node-sdk";
+import { wecomFetch, readResponseBodyAsBuffer } from "./http.js";
+// ============================================================================
+// 媒体文件解密
+// ============================================================================
+/** 企微使用 32 字节 PKCS#7 块大小（不是 AES 的 16 字节块） */
+export const WECOM_PKCS7_BLOCK_SIZE = 32;
+/**
+ * **decryptWecomMediaWithMeta (解密企业微信媒体并返回源信息)**
+ *
+ * 在返回解密结果的同时，保留下载响应中的元信息（content-type / filename / final url），
+ * 供上层更准确地推断文件后缀和 MIME。
+ */
+export async function decryptWecomMediaWithMeta(url, encodingAESKey, params) {
+    // 1. Download encrypted content
+    const res = await wecomFetch(url, undefined, { ...params?.http, timeoutMs: params?.http?.timeoutMs ?? 15_000 });
+    if (!res.ok) {
+        throw new Error(`failed to download media: ${res.status}`);
+    }
+    const sourceContentType = normalizeMime(res.headers.get("content-type"));
+    const sourceFilename = extractFilenameFromContentDisposition(res.headers.get("content-disposition"));
+    const sourceUrl = res.url || url;
+    const encryptedData = await readResponseBodyAsBuffer(res, params?.maxBytes);
+    // 2. Prepare Key and IV
+    const aesKey = decodeEncodingAESKey(encodingAESKey);
+    const iv = aesKey.subarray(0, 16);
+    // 3. Decrypt
+    const decipher = crypto.createDecipheriv("aes-256-cbc", aesKey, iv);
+    decipher.setAutoPadding(false);
+    const decryptedPadded = Buffer.concat([
+        decipher.update(encryptedData),
+        decipher.final(),
+    ]);
+    // 4. Unpad
+    // Note: Unlike msg bodies, usually removing PKCS#7 padding is enough for media files.
+    // The Python SDK logic: pad_len = decrypted_data[-1]; decrypted_data = decrypted_data[:-pad_len]
+    // Our pkcs7Unpad function does exactly this + validation.
+    return {
+        buffer: pkcs7Unpad(decryptedPadded, WECOM_PKCS7_BLOCK_SIZE),
+        sourceContentType,
+        sourceFilename,
+        sourceUrl,
+    };
+}
+// ============================================================================
+// HTTP 头信息解析（供 decryptWecomMediaWithMeta 使用）
+// ============================================================================
+/** 归一化 MIME 类型 */
+function normalizeMime(contentType) {
+    const raw = String(contentType ?? "").trim();
+    if (!raw)
+        return undefined;
+    return raw.split(";")[0]?.trim().toLowerCase() || undefined;
+}
+/** 从 Content-Disposition 提取文件名 */
+function extractFilenameFromContentDisposition(disposition) {
+    const raw = String(disposition ?? "").trim();
+    if (!raw)
+        return undefined;
+    // 优先 filename*（RFC 5987 编码）
+    const star = raw.match(/filename\*\s*=\s*([^;]+)/i);
+    if (star?.[1]) {
+        const v = star[1].trim().replace(/^UTF-8''/i, "").replace(/^"(.*)"$/, "$1");
+        try {
+            const decoded = decodeURIComponent(v);
+            if (decoded.trim())
+                return decoded.trim();
+        }
+        catch { /* ignore */ }
+        if (v.trim())
+            return v.trim();
+    }
+    // 再尝试 filename
+    const plain = raw.match(/filename\s*=\s*([^;]+)/i);
+    if (plain?.[1]) {
+        const v = plain[1].trim().replace(/^"(.*)"$/, "$1").trim();
+        if (v)
+            return v;
+    }
+    return undefined;
+}

package/dist/src/webhook/monitor.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Webhook 核心消息处理
+ *
+ * 从 @mocrane/wecom monitor.ts 部分迁移 + 重构。
+ * 负责：入站消息解析、防抖聚合、Agent 调度、流式输出、超时兜底。
+ */
+import type { WecomWebhookTarget, WebhookInboundMessage } from "./types.js";
+/**
+ * 处理入站消息
+ *
+ * 解析消息类型和内容，创建/获取 stream，加入防抖队列，返回占位符响应。
+ */
+export declare function handleInboundMessage(target: WecomWebhookTarget, message: WebhookInboundMessage, timestamp: string, nonce: string, proxyUrl?: string, msgFilterData?: {
+    senderUserId?: string;
+    chatId?: string;
+}): Promise<Record<string, unknown> | null>;
+/**
+ * 处理 stream_refresh 请求
+ *
+ * 返回 StreamState 中的当前累积内容、图片附件和 finish 标记。
+ */
+export declare function handleStreamRefresh(target: WecomWebhookTarget, message: WebhookInboundMessage): Promise<Record<string, unknown> | null>;
+/**
+ * 处理 enter_chat 事件
+ *
+ * 返回可配置的欢迎消息。
+ */
+export declare function handleEnterChat(target: WecomWebhookTarget, message: WebhookInboundMessage): Promise<Record<string, unknown> | null>;
+/**
+ * 处理模板卡片事件（对齐原版 template_card_event 逻辑）
+ *
+ * 原版流程：
+ * 1. msgid 去重：跳过已处理的卡片事件
+ * 2. 解析卡片交互数据：event_key、selected_items、task_id
+ * 3. 立即返回空加密回复（非阻塞）
+ * 4. 创建 stream 并标记开始
+ * 5. 存储 response_url（用于后续推送）
+ * 6. 构造交互描述文本，作为文本消息启动 Agent 处理
+ */
+export declare function handleTemplateCardEvent(target: WecomWebhookTarget, message: WebhookInboundMessage, timestamp: string, nonce: string, proxyUrl?: string): Promise<Record<string, unknown> | null>;
+/**
+ * **startAgentForStream (启动 Agent 处理流程)**
+ *
+ * 将接收到的（或聚合的）消息转换为 OpenClaw 内部格式，并分发给对应的 Agent。
+ * 包含：
+ * 1. 消息解密与媒体保存。
+ * 2. 路由解析 (Agent Route)。
+ * 3. 会话记录 (Session Recording)。
+ * 4. 触发 Agent 响应 (Dispatch Reply)。
+ * 5. 处理 Agent 输出（包括文本、Markdown 表格转换、<think> 标签保护、模板卡片识别）。
+ */
+export declare function startAgentForStream(params: {
+    target: WecomWebhookTarget;
+    accountId: string;
+    msg: WebhookInboundMessage;
+    streamId: string;
+    mergedContents?: string;
+    mergedMsgids?: string[];
+}): Promise<void>;