ylib-wecom-openclaw-plugin 2026.4.29

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

@@ -0,0 +1,27 @@
+/// <reference types="node" />
+/**
+ * **WecomHttpOptions (HTTP 选项)**
+ *
+ * @property proxyUrl 代理服务器地址
+ * @property timeoutMs 请求超时时间 (毫秒)
+ * @property signal AbortSignal 信号
+ */
+export declare 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,168 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+exports.__esModule = true;
+exports.readResponseBodyAsBuffer = exports.wecomFetch = void 0;
+var undici_1 = require("undici");
+var proxyDispatchers = new Map();
+/**
+ * **getProxyDispatcher (获取代理 Dispatcher)**
+ *
+ * 缓存并复用 ProxyAgent，避免重复创建连接池。
+ */
+function getProxyDispatcher(proxyUrl) {
+    var existing = proxyDispatchers.get(proxyUrl);
+    if (existing)
+        return existing;
+    var created = new undici_1.ProxyAgent(proxyUrl);
+    proxyDispatchers.set(proxyUrl, created);
+    return created;
+}
+function mergeAbortSignal(params) {
+    var 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 的调用都应经过此函数。
+ */
+function wecomFetch(input, init, opts) {
+    var _a, _b, _c, _d, _e;
+    return __awaiter(this, void 0, void 0, function () {
+        var proxyUrl, dispatcher, initSignal, signal, headers, nextInit, err_1, cause;
+        return __generator(this, function (_f) {
+            switch (_f.label) {
+                case 0:
+                    proxyUrl = (_b = (_a = opts === null || opts === void 0 ? void 0 : opts.proxyUrl) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : "";
+                    dispatcher = proxyUrl ? getProxyDispatcher(proxyUrl) : undefined;
+                    initSignal = (_c = init === null || init === void 0 ? void 0 : init.signal) !== null && _c !== void 0 ? _c : undefined;
+                    signal = mergeAbortSignal({ signal: (_d = opts === null || opts === void 0 ? void 0 : opts.signal) !== null && _d !== void 0 ? _d : initSignal, timeoutMs: opts === null || opts === void 0 ? void 0 : opts.timeoutMs });
+                    headers = new Headers((_e = init === null || init === void 0 ? void 0 : init.headers) !== null && _e !== void 0 ? _e : {});
+                    if (!headers.has("User-Agent")) {
+                        headers.set("User-Agent", "OpenClaw/2.0 (WeCom-Agent)");
+                    }
+                    nextInit = __assign(__assign(__assign(__assign({}, (init !== null && init !== void 0 ? init : {})), (signal ? { signal: signal } : {})), (dispatcher ? { dispatcher: dispatcher } : {})), { headers: headers });
+                    _f.label = 1;
+                case 1:
+                    _f.trys.push([1, 3, , 4]);
+                    return [4 /*yield*/, undici_1.fetch(input, nextInit)];
+                case 2: return [2 /*return*/, _f.sent()];
+                case 3:
+                    err_1 = _f.sent();
+                    if (err_1 instanceof Error && err_1.name === "TypeError" && err_1.message === "fetch failed") {
+                        cause = err_1.cause;
+                        console.error("[wecom-http] fetch failed: " + input + " (proxy: " + (proxyUrl || "none") + ")" + (cause ? " - cause: " + String(cause) : ""));
+                    }
+                    throw err_1;
+                case 4: return [2 /*return*/];
+            }
+        });
+    });
+}
+exports.wecomFetch = wecomFetch;
+/**
+ * **readResponseBodyAsBuffer (读取响应 Body)**
+ *
+ * 将 Response Body 读取为 Buffer，支持最大字节限制以防止内存溢出。
+ * 适用于下载媒体文件等场景。
+ */
+function readResponseBodyAsBuffer(res, maxBytes) {
+    return __awaiter(this, void 0, void 0, function () {
+        var limit, chunks, total, reader, _a, done, value, _b;
+        return __generator(this, function (_c) {
+            switch (_c.label) {
+                case 0:
+                    if (!res.body)
+                        return [2 /*return*/, Buffer.alloc(0)];
+                    limit = maxBytes && Number.isFinite(maxBytes) && maxBytes > 0 ? maxBytes : undefined;
+                    chunks = [];
+                    total = 0;
+                    reader = res.body.getReader();
+                    _c.label = 1;
+                case 1:
+                    if (!true) return [3 /*break*/, 8];
+                    return [4 /*yield*/, reader.read()];
+                case 2:
+                    _a = _c.sent(), done = _a.done, value = _a.value;
+                    if (done)
+                        return [3 /*break*/, 8];
+                    if (!value)
+                        return [3 /*break*/, 1];
+                    total += value.byteLength;
+                    if (!(limit && total > limit)) return [3 /*break*/, 7];
+                    _c.label = 3;
+                case 3:
+                    _c.trys.push([3, 5, , 6]);
+                    return [4 /*yield*/, reader.cancel("body too large")];
+                case 4:
+                    _c.sent();
+                    return [3 /*break*/, 6];
+                case 5:
+                    _b = _c.sent();
+                    return [3 /*break*/, 6];
+                case 6: throw new Error("response body too large (>" + limit + " bytes)");
+                case 7:
+                    chunks.push(value);
+                    return [3 /*break*/, 1];
+                case 8: return [2 /*return*/, Buffer.concat(chunks.map(function (c) { return Buffer.from(c); }))];
+            }
+        });
+    });
+}
+exports.readResponseBodyAsBuffer = readResponseBodyAsBuffer;

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,43 @@
+"use strict";
+/**
+ * Webhook 模块公共入口
+ *
+ * Re-export 所有 Webhook 模式对外暴露的函数和类型。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+exports.__esModule = true;
+// ── Handler ─────────────────────────────────────────────────────────
+var handler_js_1 = require("./handler.js");
+__createBinding(exports, handler_js_1, "handleWecomWebhookRequest");
+// ── Target ──────────────────────────────────────────────────────────
+var target_js_1 = require("./target.js");
+__createBinding(exports, target_js_1, "registerWecomWebhookTarget");
+__createBinding(exports, target_js_1, "getRegisteredTargets");
+__createBinding(exports, target_js_1, "getWebhookTargetsMap");
+__createBinding(exports, target_js_1, "hasActiveTargets");
+__createBinding(exports, target_js_1, "parseWebhookPath");
+// ── Gateway ─────────────────────────────────────────────────────────
+var gateway_js_1 = require("./gateway.js");
+__createBinding(exports, gateway_js_1, "startWebhookGateway");
+__createBinding(exports, gateway_js_1, "stopWebhookGateway");
+__createBinding(exports, gateway_js_1, "getMonitorState");
+var types_js_1 = require("./types.js");
+__createBinding(exports, types_js_1, "STREAM_TTL_MS");
+__createBinding(exports, types_js_1, "ACTIVE_REPLY_TTL_MS");
+__createBinding(exports, types_js_1, "DEFAULT_DEBOUNCE_MS");
+__createBinding(exports, types_js_1, "STREAM_MAX_BYTES");
+__createBinding(exports, types_js_1, "BOT_WINDOW_MS");
+__createBinding(exports, types_js_1, "BOT_SWITCH_MARGIN_MS");
+__createBinding(exports, types_js_1, "REQUEST_TIMEOUT_MS");
+__createBinding(exports, types_js_1, "PRUNE_INTERVAL_MS");
+__createBinding(exports, types_js_1, "WEBHOOK_PATHS");
+// ── State (全局单例) ────────────────────────────────────────────────
+var state_js_1 = require("./state.js");
+__createBinding(exports, state_js_1, "monitorState");
+__createBinding(exports, state_js_1, "WebhookMonitorState");

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

@@ -0,0 +1,30 @@
+/**
+ * Webhook 入站媒体处理
+ *
+ * 从 @mocrane/wecom media.ts 部分迁移（仅入站解密）。
+ * 负责：AES-CBC 解密企微加密媒体文件、MIME 类型检测。
+ */
+/// <reference types="node" />
+import { WecomHttpOptions } from "./http.js";
+/** 企微使用 32 字节 PKCS#7 块大小（不是 AES 的 16 字节块） */
+export declare const WECOM_PKCS7_BLOCK_SIZE = 32;
+/** 解密后的媒体文件及源信息（对齐原版 DecryptedWecomMedia） */
+export declare 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,152 @@
+"use strict";
+/**
+ * Webhook 入站媒体处理
+ *
+ * 从 @mocrane/wecom media.ts 部分迁移（仅入站解密）。
+ * 负责：AES-CBC 解密企微加密媒体文件、MIME 类型检测。
+ */
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+exports.__esModule = true;
+exports.decryptWecomMediaWithMeta = exports.WECOM_PKCS7_BLOCK_SIZE = void 0;
+var node_crypto_1 = __importDefault(require("node:crypto"));
+var aibot_node_sdk_1 = require("@wecom/aibot-node-sdk");
+var http_js_1 = require("./http.js");
+// ============================================================================
+// 媒体文件解密
+// ============================================================================
+/** 企微使用 32 字节 PKCS#7 块大小（不是 AES 的 16 字节块） */
+exports.WECOM_PKCS7_BLOCK_SIZE = 32;
+/**
+ * **decryptWecomMediaWithMeta (解密企业微信媒体并返回源信息)**
+ *
+ * 在返回解密结果的同时，保留下载响应中的元信息（content-type / filename / final url），
+ * 供上层更准确地推断文件后缀和 MIME。
+ */
+function decryptWecomMediaWithMeta(url, encodingAESKey, params) {
+    var _a, _b;
+    return __awaiter(this, void 0, void 0, function () {
+        var res, sourceContentType, sourceFilename, sourceUrl, encryptedData, aesKey, iv, decipher, decryptedPadded;
+        return __generator(this, function (_c) {
+            switch (_c.label) {
+                case 0: return [4 /*yield*/, http_js_1.wecomFetch(url, undefined, __assign(__assign({}, params === null || params === void 0 ? void 0 : params.http), { timeoutMs: (_b = (_a = params === null || params === void 0 ? void 0 : params.http) === null || _a === void 0 ? void 0 : _a.timeoutMs) !== null && _b !== void 0 ? _b : 15000 }))];
+                case 1:
+                    res = _c.sent();
+                    if (!res.ok) {
+                        throw new Error("failed to download media: " + res.status);
+                    }
+                    sourceContentType = normalizeMime(res.headers.get("content-type"));
+                    sourceFilename = extractFilenameFromContentDisposition(res.headers.get("content-disposition"));
+                    sourceUrl = res.url || url;
+                    return [4 /*yield*/, http_js_1.readResponseBodyAsBuffer(res, params === null || params === void 0 ? void 0 : params.maxBytes)];
+                case 2:
+                    encryptedData = _c.sent();
+                    aesKey = aibot_node_sdk_1.decodeEncodingAESKey(encodingAESKey);
+                    iv = aesKey.subarray(0, 16);
+                    decipher = node_crypto_1["default"].createDecipheriv("aes-256-cbc", aesKey, iv);
+                    decipher.setAutoPadding(false);
+                    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 [2 /*return*/, {
+                            buffer: aibot_node_sdk_1.pkcs7Unpad(decryptedPadded, exports.WECOM_PKCS7_BLOCK_SIZE),
+                            sourceContentType: sourceContentType,
+                            sourceFilename: sourceFilename,
+                            sourceUrl: sourceUrl
+                        }];
+            }
+        });
+    });
+}
+exports.decryptWecomMediaWithMeta = decryptWecomMediaWithMeta;
+// ============================================================================
+// HTTP 头信息解析（供 decryptWecomMediaWithMeta 使用）
+// ============================================================================
+/** 归一化 MIME 类型 */
+function normalizeMime(contentType) {
+    var _a;
+    var raw = String(contentType !== null && contentType !== void 0 ? contentType : "").trim();
+    if (!raw)
+        return undefined;
+    return ((_a = raw.split(";")[0]) === null || _a === void 0 ? void 0 : _a.trim().toLowerCase()) || undefined;
+}
+/** 从 Content-Disposition 提取文件名 */
+function extractFilenameFromContentDisposition(disposition) {
+    var raw = String(disposition !== null && disposition !== void 0 ? disposition : "").trim();
+    if (!raw)
+        return undefined;
+    // 优先 filename*（RFC 5987 编码）
+    var star = raw.match(/filename\*\s*=\s*([^;]+)/i);
+    if (star === null || star === void 0 ? void 0 : star[1]) {
+        var v = star[1].trim().replace(/^UTF-8''/i, "").replace(/^"(.*)"$/, "$1");
+        try {
+            var decoded = decodeURIComponent(v);
+            if (decoded.trim())
+                return decoded.trim();
+        }
+        catch ( /* ignore */_a) { /* ignore */ }
+        if (v.trim())
+            return v.trim();
+    }
+    // 再尝试 filename
+    var plain = raw.match(/filename\s*=\s*([^;]+)/i);
+    if (plain === null || plain === void 0 ? void 0 : plain[1]) {
+        var 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>;