ylib-wecom-openclaw-plugin 2026.4.29

package/dist/src/webhook/handler.js

@@ -0,0 +1,481 @@
+"use strict";
+/**
+ * Webhook HTTP 请求处理
+ *
+ * 从 @mocrane/wecom monitor.ts handleWecomWebhookRequest 部分迁移 + 重构。
+ * 负责：
+ * 1. GET/POST 请求分流
+ * 2. 签名验证（调用 crypto 模块）
+ * 3. 消息解密
+ * 4. 按消息类型分发到 monitor 层
+ */
+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.handleWecomWebhookRequest = void 0;
+var node_crypto_1 = __importDefault(require("node:crypto"));
+var target_js_1 = require("./target.js");
+var utils_js_1 = require("../utils.js");
+var monitor_js_1 = require("./monitor.js");
+var target_js_2 = require("./target.js");
+var helpers_js_1 = require("./helpers.js");
+var aibot_node_sdk_1 = require("@wecom/aibot-node-sdk");
+// ============================================================================
+// 辅助函数
+// ============================================================================
+/** 解析 URL 查询参数 */
+function parseQuery(url) {
+    var idx = url.indexOf("?");
+    if (idx < 0)
+        return {};
+    var params = new URLSearchParams(url.slice(idx + 1));
+    var result = {};
+    for (var _i = 0, params_1 = params; _i < params_1.length; _i++) {
+        var _a = params_1[_i], key = _a[0], value = _a[1];
+        result[key] = value;
+    }
+    return result;
+}
+/**
+ * 从查询参数中提取签名字段
+ *
+ * 企微不同场景下签名参数名不一致，按优先级依次尝试：
+ * msg_signature → msgsignature → signature
+ */
+function resolveSignatureParam(query) {
+    var _a, _b, _c;
+    return (_c = (_b = (_a = query.msg_signature) !== null && _a !== void 0 ? _a : query.msgsignature) !== null && _b !== void 0 ? _b : query.signature) !== null && _c !== void 0 ? _c : "";
+}
+/**
+ * 判断入站消息是否应该被处理（对齐原版 shouldProcessBotInboundMessage）
+ *
+ * 仅允许"真实用户消息"进入 Bot 会话：
+ * - 发送者缺失 → 丢弃（避免 unknown 会话串会话）
+ * - 发送者是 sys → 丢弃（避免系统回调触发 AI 自动回复）
+ * - 群消息缺失 chatid → 丢弃（避免 group:unknown 串群）
+ */
+function shouldProcessBotInboundMessage(msg) {
+    var _a, _b, _c;
+    var senderUserId = (_a = helpers_js_1.resolveWecomSenderUserId(msg)) === null || _a === void 0 ? void 0 : _a.trim();
+    if (!senderUserId) {
+        return { shouldProcess: false, reason: "missing_sender" };
+    }
+    if (senderUserId.toLowerCase() === "sys") {
+        return { shouldProcess: false, reason: "system_sender" };
+    }
+    // 企微 Bot 回调中 chattype 是扁平字段（非嵌套在 chat_info 内）
+    var chatType = String((_b = msg.chattype) !== null && _b !== void 0 ? _b : "").trim().toLowerCase();
+    if (chatType === "group") {
+        var chatId = (_c = msg.chatid) === null || _c === void 0 ? void 0 : _c.trim();
+        if (!chatId) {
+            return { shouldProcess: false, reason: "missing_chatid", senderUserId: senderUserId };
+        }
+        return { shouldProcess: true, reason: "user_message", senderUserId: senderUserId, chatId: chatId };
+    }
+    return { shouldProcess: true, reason: "user_message", senderUserId: senderUserId, chatId: senderUserId };
+}
+/**
+ * 从 Target 配置中提取预期的 Bot Identity 集合
+ *
+ * 用于 aibotid 校验：即使签名匹配，也要确认消息来自预期的 Bot。
+ *
+ * 配置来源（对齐用户 YAML 配置）：
+ * - 单账号模式：channels.wecom.botId
+ * - 多账号模式：channels.wecom.accounts.xxx.botId
+ *
+ * 解析后的 botId 已在 account.botId 中，直接读取即可。
+ * 同时兼容 config 中可能存在的 aibotid（原版字段名）。
+ */
+function resolveBotIdentitySet(target) {
+    var _a, _b;
+    var ids = new Set();
+    // account.botId — 从 YAML 配置中解析出的 botId（单账号/多账号均可）
+    var botId = (_a = target.account.botId) === null || _a === void 0 ? void 0 : _a.trim();
+    if (botId)
+        ids.add(botId);
+    // config.botId — 与 account.botId 相同来源（兜底）
+    var configBotId = (_b = target.account.config.botId) === null || _b === void 0 ? void 0 : _b.trim();
+    if (configBotId)
+        ids.add(configBotId);
+    return ids;
+}
+/** POST body 最大允许字节数 (1 MB) */
+var MAX_BODY_BYTES = 1024 * 1024;
+/**
+ * 读取 HTTP 请求 body（带大小限制保护）
+ *
+ * 超过 maxBytes 时会主动销毁请求并拒绝，防止大包攻击。
+ */
+function readBody(req, maxBytes) {
+    if (maxBytes === void 0) { maxBytes = MAX_BODY_BYTES; }
+    return new Promise(function (resolve) {
+        var chunks = [];
+        var total = 0;
+        req.on("data", function (chunk) {
+            total += chunk.length;
+            if (total > maxBytes) {
+                resolve({ ok: false, error: "payload too large" });
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", function () {
+            var raw = Buffer.concat(chunks).toString("utf8");
+            if (!raw.trim()) {
+                resolve({ ok: false, error: "empty payload" });
+                return;
+            }
+            resolve({ ok: true, value: raw });
+        });
+        req.on("error", function (err) {
+            resolve({ ok: false, error: err instanceof Error ? err.message : String(err) });
+        });
+    });
+}
+/** 构造加密 JSON 响应（返回对象，不做 stringify） */
+function encryptResponse(target, responseData, timestamp, nonce) {
+    var plaintext = JSON.stringify(responseData);
+    var wc = new aibot_node_sdk_1.WecomCrypto(target.account.token, target.account.encodingAESKey, target.account.receiveId);
+    var _a = wc.encrypt(plaintext, timestamp, nonce), encrypt = _a.encrypt, signature = _a.signature;
+    return { encrypt: encrypt, msgsignature: signature, timestamp: timestamp, nonce: nonce };
+}
+/** 发送 JSON 响应 (Content-Type: application/json) */
+function sendJson(res, statusCode, data) {
+    res.writeHead(statusCode, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(data));
+}
+/**
+ * 发送加密回复响应 (Content-Type: text/plain)
+ *
+ * 企微官方参考实现要求加密 JSON 以 text/plain 返回。
+ */
+function sendEncryptedReply(res, data) {
+    res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end(JSON.stringify(data));
+}
+/** 发送纯文本响应 */
+function sendText(res, statusCode, text) {
+    res.writeHead(statusCode, { "Content-Type": "text/plain charset=utf-8" });
+    res.end(text);
+}
+// ============================================================================
+// 路径解析
+// ============================================================================
+/**
+ * 标准化 Webhook 路径（不含 query string）
+ */
+function normalizeRequestPath(url) {
+    var idx = url.indexOf("?");
+    var pathname = idx >= 0 ? url.slice(0, idx) : url;
+    var trimmed = pathname.trim();
+    if (!trimmed || trimmed === "/")
+        return "/";
+    var withSlash = trimmed.startsWith("/") ? trimmed : "/" + trimmed;
+    if (withSlash.length > 1 && withSlash.endsWith("/"))
+        return withSlash.slice(0, -1);
+    return withSlash;
+}
+/** 按 accountId 去重 Target 列表（同一 account 注册多条路径时只保留第一个） */
+function deduplicateByAccountId(targets) {
+    var seen = new Set();
+    var result = [];
+    for (var _i = 0, targets_1 = targets; _i < targets_1.length; _i++) {
+        var target = targets_1[_i];
+        if (!seen.has(target.account.accountId)) {
+            seen.add(target.account.accountId);
+            result.push(target);
+        }
+    }
+    return result;
+}
+/**
+ * 从已注册的 Target 中匹配签名
+ *
+ * 匹配策略：
+ * 1. 如果路径中有 accountId，优先精确匹配
+ * 2. 用 filter 收集所有签名匹配的 Target
+ * 3. 检查冲突：0 个 = not_found，1 个 = matched，>1 个 = conflict
+ *
+ * 与原版保持一致：检查 target.account.token 存在性，防止空 token 的误匹配。
+ */
+function findMatchingTarget(requestPath, signature, timestamp, nonce, encrypt, pathAccountId) {
+    var _a;
+    // 收集所有候选 Target（路径匹配 + 全局兜底）
+    var targetsMap = target_js_1.getWebhookTargetsMap();
+    var normalizedPath = normalizeRequestPath(requestPath);
+    var pathTargets = targetsMap.get(normalizedPath);
+    // 如果路径中有 accountId，优先精确匹配
+    if (pathAccountId && pathTargets) {
+        var byAccountId = pathTargets.find(function (t) { return t.account.accountId === pathAccountId; });
+        if ((_a = byAccountId === null || byAccountId === void 0 ? void 0 : byAccountId.account) === null || _a === void 0 ? void 0 : _a.token) {
+            var wc = new aibot_node_sdk_1.WecomCrypto(byAccountId.account.token, byAccountId.account.encodingAESKey, byAccountId.account.receiveId);
+            var ok = wc.verifySignature(signature, timestamp, nonce, encrypt);
+            if (ok)
+                return { status: "matched", target: byAccountId };
+        }
+    }
+    // 收集候选列表（路径匹配优先，否则全局遍历）
+    var candidates = (pathTargets && pathTargets.length > 0)
+        ? pathTargets
+        : target_js_1.getRegisteredTargets();
+    // filter 语义：收集所有签名匹配的 Target
+    var signatureMatches = candidates.filter(function (target) {
+        var _a;
+        if (!((_a = target === null || target === void 0 ? void 0 : target.account) === null || _a === void 0 ? void 0 : _a.token))
+            return false;
+        var wc = new aibot_node_sdk_1.WecomCrypto(target.account.token, target.account.encodingAESKey, target.account.receiveId);
+        return wc.verifySignature(signature, timestamp, nonce, encrypt);
+    });
+    // 按 accountId 去重（同一 account 注册多条路径时，不应被误判为冲突）
+    var uniqueMatches = deduplicateByAccountId(signatureMatches);
+    if (uniqueMatches.length === 1) {
+        return { status: "matched", target: uniqueMatches[0] };
+    }
+    var candidateAccountIds = (uniqueMatches.length > 0 ? uniqueMatches : candidates)
+        .map(function (t) { return t.account.accountId; });
+    if (uniqueMatches.length === 0) {
+        return { status: "not_found", candidateAccountIds: candidateAccountIds };
+    }
+    // uniqueMatches.length > 1 → 多账号冲突
+    return { status: "conflict", candidateAccountIds: candidateAccountIds };
+}
+// ============================================================================
+// 主入口
+// ============================================================================
+/**
+ * Webhook HTTP 请求总入口
+ *
+ * 处理企微 Bot Webhook 的 GET（URL 验证）和 POST（消息回调）请求。
+ * 返回 true 表示已处理，false 表示不匹配（交给其他 handler）。
+ */
+function handleWecomWebhookRequest(req, res) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0;
+    return __awaiter(this, void 0, void 0, function () {
+        var reqId, url, method, remote, ua, cl, query, hasTimestamp, hasNonce, hasEchostr, signature, hasSig, pathAccountId, timestamp, nonce, echostr, msgSignature, matchResult, target, wc, plaintext, timestamp, nonce, msgSignature, bodyResult, bodyStr, body, encrypt, matchResult, reason, detail, target, message, wc, plaintext, expectedBotIds, inboundAibotId, proxyUrl, responseData, encrypted, encrypted, err_1, errorResponse, encrypted;
+        return __generator(this, function (_1) {
+            switch (_1.label) {
+                case 0:
+                    reqId = node_crypto_1["default"].randomUUID().slice(0, 8);
+                    url = (_a = req.url) !== null && _a !== void 0 ? _a : "/";
+                    method = ((_b = req.method) !== null && _b !== void 0 ? _b : "GET").toUpperCase();
+                    remote = (_d = (_c = req.socket) === null || _c === void 0 ? void 0 : _c.remoteAddress) !== null && _d !== void 0 ? _d : "unknown";
+                    ua = String((_e = req.headers["user-agent"]) !== null && _e !== void 0 ? _e : "");
+                    cl = String((_f = req.headers["content-length"]) !== null && _f !== void 0 ? _f : "");
+                    query = parseQuery(url);
+                    hasTimestamp = Boolean(query.timestamp);
+                    hasNonce = Boolean(query.nonce);
+                    hasEchostr = Boolean(query.echostr);
+                    signature = resolveSignatureParam(query);
+                    hasSig = Boolean(signature);
+                    console.log("[wecom] inbound(http): reqId=" + reqId + " path=" + url.split("?")[0] + " method=" + method + " remote=" + remote + " ua=" + (ua ? "\"" + ua + "\"" : "N/A") + " contentLength=" + (cl || "N/A") + " query={timestamp:" + hasTimestamp + ",nonce:" + hasNonce + ",echostr:" + hasEchostr + ",signature:" + hasSig + "}");
+                    if (!target_js_2.hasActiveTargets()) {
+                        console.log("[wecom] inbound(http): reqId=" + reqId + " skipped \u2014 no active targets");
+                        return [2 /*return*/, false]; // 无注册 Target，不处理
+                    }
+                    pathAccountId = target_js_1.parseWebhookPath(url);
+                    // ── GET 请求：URL 验证 ──────────────────────────────────────────
+                    if (method === "GET") {
+                        timestamp = query.timestamp, nonce = query.nonce, echostr = query.echostr;
+                        msgSignature = resolveSignatureParam(query);
+                        if (!msgSignature || !timestamp || !nonce || !echostr) {
+                            sendText(res, 400, "missing required query parameters");
+                            return [2 /*return*/, true];
+                        }
+                        matchResult = findMatchingTarget(url, msgSignature, timestamp, nonce, echostr, pathAccountId);
+                        if (matchResult.status !== "matched") {
+                            console.log("[wecom] inbound(http): reqId=" + reqId + " GET route_failure reason=" + matchResult.status + " candidates=[" + matchResult.candidateAccountIds.join(",") + "]");
+                            sendText(res, 403, "signature verification failed");
+                            return [2 /*return*/, true];
+                        }
+                        target = matchResult.target;
+                        (_h = (_g = target.runtime).log) === null || _h === void 0 ? void 0 : _h.call(_g, "[webhook] GET URL \u9A8C\u8BC1\u6210\u529F (account=" + target.account.accountId + ")");
+                        try {
+                            wc = new aibot_node_sdk_1.WecomCrypto(target.account.token, target.account.encodingAESKey, target.account.receiveId);
+                            plaintext = wc.decrypt(echostr);
+                            sendText(res, 200, plaintext);
+                        }
+                        catch (err) {
+                            (_k = (_j = target.runtime).log) === null || _k === void 0 ? void 0 : _k.call(_j, "[webhook] echostr \u89E3\u5BC6\u5931\u8D25: " + (err instanceof Error ? err.message : String(err)));
+                            sendText(res, 403, "decryption failed");
+                        }
+                        return [2 /*return*/, true];
+                    }
+                    if (!(method === "POST")) return [3 /*break*/, 6];
+                    timestamp = query.timestamp, nonce = query.nonce;
+                    msgSignature = resolveSignatureParam(query);
+                    if (!msgSignature || !timestamp || !nonce) {
+                        sendJson(res, 400, { error: "missing required query parameters" });
+                        return [2 /*return*/, true];
+                    }
+                    return [4 /*yield*/, readBody(req)];
+                case 1:
+                    bodyResult = _1.sent();
+                    if (!bodyResult.ok) {
+                        sendJson(res, 400, { error: bodyResult.error });
+                        return [2 /*return*/, true];
+                    }
+                    bodyStr = bodyResult.value;
+                    body = void 0;
+                    try {
+                        body = JSON.parse(bodyStr);
+                    }
+                    catch (_2) {
+                        sendJson(res, 400, { error: "invalid JSON body" });
+                        return [2 /*return*/, true];
+                    }
+                    encrypt = String((_m = (_l = body.encrypt) !== null && _l !== void 0 ? _l : body.Encrypt) !== null && _m !== void 0 ? _m : "");
+                    // POST body 诊断日志（不输出 encrypt 内容）
+                    console.log("[wecom] inbound(bot): reqId=" + reqId + " rawJsonBytes=" + Buffer.byteLength(bodyStr, "utf8") + " hasEncrypt=" + Boolean(encrypt) + " encryptLen=" + encrypt.length);
+                    if (!encrypt) {
+                        sendJson(res, 400, { error: "missing encrypt field" });
+                        return [2 /*return*/, true];
+                    }
+                    matchResult = findMatchingTarget(url, msgSignature, timestamp, nonce, encrypt, pathAccountId);
+                    if (matchResult.status !== "matched") {
+                        reason = matchResult.status === "conflict"
+                            ? "wecom_account_conflict"
+                            : "wecom_account_not_found";
+                        detail = matchResult.status === "conflict"
+                            ? "Bot callback account conflict: multiple accounts matched signature."
+                            : "Bot callback account not found: signature verification failed.";
+                        console.log("[wecom] inbound(bot): reqId=" + reqId + " route_failure reason=" + reason + " path=" + url.split("?")[0] + " candidates=[" + matchResult.candidateAccountIds.join(",") + "]");
+                        sendText(res, 403, detail);
+                        return [2 /*return*/, true];
+                    }
+                    target = matchResult.target;
+                    (_p = (_o = target.runtime).log) === null || _p === void 0 ? void 0 : _p.call(_o, "[webhook] POST \u7B7E\u540D\u9A8C\u8BC1\u6210\u529F (account=" + target.account.accountId + ")");
+                    // 更新状态：最后接收消息时间
+                    (_q = target.statusSink) === null || _q === void 0 ? void 0 : _q.call(target, { lastInboundAt: Date.now() });
+                    message = void 0;
+                    try {
+                        wc = new aibot_node_sdk_1.WecomCrypto(target.account.token, target.account.encodingAESKey, target.account.receiveId);
+                        plaintext = wc.decrypt(encrypt);
+                        message = JSON.parse(plaintext);
+                    }
+                    catch (err) {
+                        (_s = (_r = target.runtime).log) === null || _s === void 0 ? void 0 : _s.call(_r, "[webhook] \u6D88\u606F\u89E3\u5BC6\u5931\u8D25: " + (err instanceof Error ? err.message : String(err)));
+                        // 解密失败返回 400 + 可读错误信息（与原版一致，方便排查 EncodingAESKey 配置错误）
+                        sendText(res, 400, "decrypt failed - 解密失败，请检查 EncodingAESKey");
+                        return [2 /*return*/, true];
+                    }
+                    expectedBotIds = resolveBotIdentitySet(target);
+                    if (expectedBotIds.size > 0) {
+                        inboundAibotId = String((_t = message.aibotid) !== null && _t !== void 0 ? _t : "").trim();
+                        if (!inboundAibotId || !expectedBotIds.has(inboundAibotId)) {
+                            (_v = (_u = target.runtime).error) === null || _v === void 0 ? void 0 : _v.call(_u, "[webhook] aibotid_mismatch: accountId=" + target.account.accountId + " expected=" + Array.from(expectedBotIds).join(",") + " actual=" + (inboundAibotId || "N/A"));
+                        }
+                    }
+                    (_x = (_w = target.runtime).log) === null || _x === void 0 ? void 0 : _x.call(_w, "[webhook] \u6536\u5230\u6D88\u606F (type=" + message.msgtype + ", msgid=" + ((_y = message.msgid) !== null && _y !== void 0 ? _y : "N/A") + ", account=" + target.account.accountId + ")");
+                    proxyUrl = utils_js_1.resolveWecomEgressProxyUrl(target.config);
+                    _1.label = 2;
+                case 2:
+                    _1.trys.push([2, 4, , 5]);
+                    return [4 /*yield*/, dispatchMessage(target, message, timestamp, nonce, proxyUrl)];
+                case 3:
+                    responseData = _1.sent();
+                    if (responseData) {
+                        encrypted = encryptResponse(target, responseData, timestamp, nonce);
+                        sendEncryptedReply(res, encrypted);
+                    }
+                    else {
+                        encrypted = encryptResponse(target, {}, timestamp, nonce);
+                        sendEncryptedReply(res, encrypted);
+                    }
+                    return [3 /*break*/, 5];
+                case 4:
+                    err_1 = _1.sent();
+                    (_0 = (_z = target.runtime).error) === null || _0 === void 0 ? void 0 : _0.call(_z, "[webhook] \u6D88\u606F\u5904\u7406\u5F02\u5E38: " + (err_1 instanceof Error ? err_1.message : String(err_1)));
+                    errorResponse = {
+                        msgtype: "text",
+                        text: { content: "服务内部错误：Bot 处理异常，请稍后重试。" }
+                    };
+                    encrypted = encryptResponse(target, errorResponse, timestamp, nonce);
+                    sendEncryptedReply(res, encrypted);
+                    return [3 /*break*/, 5];
+                case 5: return [2 /*return*/, true];
+                case 6: return [2 /*return*/, false];
+            }
+        });
+    });
+}
+exports.handleWecomWebhookRequest = handleWecomWebhookRequest;
+// ============================================================================
+// 消息分发
+// ============================================================================
+/**
+ * 根据消息类型分发到对应的处理函数
+ */
+function dispatchMessage(target, message, timestamp, nonce, proxyUrl) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    return __awaiter(this, void 0, void 0, function () {
+        var msgtype, eventType, filterResult;
+        return __generator(this, function (_l) {
+            msgtype = message.msgtype;
+            // stream_refresh 轮询
+            if (msgtype === "stream") {
+                return [2 /*return*/, monitor_js_1.handleStreamRefresh(target, message)];
+            }
+            // 事件处理
+            if (msgtype === "event") {
+                eventType = String((_b = (_a = message.event) === null || _a === void 0 ? void 0 : _a.eventtype) !== null && _b !== void 0 ? _b : "").toLowerCase();
+                if (eventType === "enter_chat") {
+                    return [2 /*return*/, monitor_js_1.handleEnterChat(target, message)];
+                }
+                if (eventType === "template_card_event") {
+                    return [2 /*return*/, monitor_js_1.handleTemplateCardEvent(target, message, timestamp, nonce, proxyUrl)];
+                }
+                (_d = (_c = target.runtime).log) === null || _d === void 0 ? void 0 : _d.call(_c, "[webhook] \u672A\u5904\u7406\u7684\u4E8B\u4EF6\u7C7B\u578B: " + eventType);
+                return [2 /*return*/, null];
+            }
+            // 普通消息（text / image / file / voice / video / mixed）
+            if (["text", "image", "file", "voice", "video", "mixed"].includes(msgtype)) {
+                filterResult = shouldProcessBotInboundMessage(message);
+                if (!filterResult.shouldProcess) {
+                    (_f = (_e = target.runtime).log) === null || _f === void 0 ? void 0 : _f.call(_e, "[webhook] \u6D88\u606F\u8FC7\u6EE4: msgtype=" + msgtype + " reason=" + filterResult.reason + " from=" + ((_g = helpers_js_1.resolveWecomSenderUserId(message)) !== null && _g !== void 0 ? _g : "N/A") + " chatType=" + String((_h = message.chattype) !== null && _h !== void 0 ? _h : "N/A"));
+                    return [2 /*return*/, null];
+                }
+                return [2 /*return*/, monitor_js_1.handleInboundMessage(target, message, timestamp, nonce, proxyUrl, filterResult)];
+            }
+            (_k = (_j = target.runtime).log) === null || _k === void 0 ? void 0 : _k.call(_j, "[webhook] \u672A\u77E5\u6D88\u606F\u7C7B\u578B: " + msgtype);
+            return [2 /*return*/, null];
+        });
+    });
+}

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

@@ -0,0 +1,157 @@
+/**
+ * Webhook 辅助函数
+ *
+ * 从 @mocrane/wecom monitor.ts 迁移的辅助工具函数集合。
+ * 包含：文本截断、兜底提示构建、本机路径提取、MIME 推断等。
+ */
+/// <reference types="node" />
+import type { OpenClawConfig } from "ylib-openclaw/plugin-sdk";
+import type { StreamState, WecomWebhookTarget, WebhookInboundMessage, WebhookInboundQuote } from "./types.js";
+/** DM 文本最大字节数上限 */
+export declare const STREAM_MAX_DM_BYTES = 200000;
+/** MIME 扩展名映射表 */
+export declare const MIME_BY_EXT: Record<string, string>;
+/**
+ * UTF-8 字节截断（保留尾部，截断头部）
+ *
+ * 对齐原版 truncateUtf8Bytes：保留最后 maxBytes 字节。
+ */
+export declare function truncateUtf8Bytes(text: string, maxBytes: number): string;
+/**
+ * 追加 DM 兜底内容（对齐原版 appendDmContent）
+ *
+ * 每次 deliver 时都追加到 dmContent（不受 STREAM_MAX_BYTES 限制，有 DM 上限保护）
+ */
+export declare function appendDmContent(state: StreamState, text: string): void;
+/**
+ * 构建兜底提示文本（对齐原版 buildFallbackPrompt）
+ */
+export declare function buildFallbackPrompt(params: {
+    kind: "media" | "timeout" | "error";
+    agentConfigured: boolean;
+    userId?: string;
+    filename?: string;
+    chatType?: "group" | "direct";
+}): string;
+/**
+ * 从文本中提取本机文件路径（对齐原版 extractLocalFilePathsFromText）
+ */
+export declare function extractLocalFilePathsFromText(text: string): string[];
+/**
+ * 从文本中提取本机图片路径（对齐原版 extractLocalImagePathsFromText）
+ *
+ * 仅提取 text 中存在且也出现在 mustAlsoAppearIn 中的路径（安全：防止泄漏）
+ */
+export declare function extractLocalImagePathsFromText(params: {
+    text: string;
+    mustAlsoAppearIn: string;
+}): string[];
+/**
+ * 判断文本是否包含"发送本机文件"的意图（对齐原版 looksLikeSendLocalFileIntent）
+ */
+export declare function looksLikeSendLocalFileIntent(rawBody: string): boolean;
+/**
+ * 计算 taskKey（对齐原版 computeTaskKey）
+ */
+export declare function computeTaskKey(target: WecomWebhookTarget, msg: WebhookInboundMessage): string | undefined;
+/**
+ * 检查 Agent 凭证是否已配置（对齐原版 resolveAgentAccountOrUndefined 的简化版）
+ *
+ * 在 webhook 模式下，Agent 凭证直接来自 target.account，不需要复杂的解析
+ */
+export declare function isAgentConfigured(target: WecomWebhookTarget): boolean;
+/**
+ * 从路径猜测 content-type
+ */
+export declare function guessContentTypeFromPath(filePath: string): string | undefined;
+/**
+ * 从 StreamState 构建最终流式回复（对齐原版 buildStreamReplyFromState）
+ *
+ * 包含 images/msg_item，对 content 做 truncateUtf8Bytes。
+ */
+export declare function buildStreamReplyFromState(state: StreamState, maxBytes: number): Record<string, unknown>;
+/**
+ * 计算 MD5
+ */
+export declare function computeMd5(data: Buffer | string): string;
+/**
+ * 解析媒体最大字节数（对齐原版 resolveWecomMediaMaxBytes）
+ */
+export declare function resolveWecomMediaMaxBytes(cfg: OpenClawConfig): number;
+/** 入站消息解析结果（对齐原版 InboundResult） */
+export declare type InboundResult = {
+    body: string;
+    media?: {
+        buffer: Buffer;
+        contentType: string;
+        filename: string;
+    };
+};
+/**
+ * 处理接收消息（对齐原版 processInboundMessage）
+ *
+ * 解析企业微信传入的消息体：
+ * 1. 识别媒体消息（Image/File/Video/Mixed）
+ * 2. 如果存在媒体文件，调用 media.ts 进行解密和下载
+ * 3. 通过 inferInboundMediaMeta 精确推断 MIME 和文件名
+ * 4. 构造统一的 InboundResult 供后续 Agent 处理
+ *
+ * @param target Webhook 目标配置
+ * @param msg 企业微信原始消息对象
+ */
+export declare function processInboundMessage(target: WecomWebhookTarget, msg: WebhookInboundMessage): Promise<InboundResult>;
+/**
+ * 构建 Agent 调度所需的 config（对齐原版 cfgForDispatch 逻辑）
+ *
+ * 关键修改：
+ * - tools.deny += "message"（防止 Agent 绕过 Bot 交付）
+ * - blockStreamingChunk / blockStreamingCoalesce 使用更小的阈值
+ */
+export declare function buildCfgForDispatch(config: OpenClawConfig): OpenClawConfig;
+/**
+ * 解析企微 Bot 回调中的发送者 userid（对齐原版 resolveWecomSenderUserId）
+ *
+ * 优先级：from.userid → fromuserid → from_userid → fromUserId
+ */
+export declare function resolveWecomSenderUserId(msg: WebhookInboundMessage): string | undefined;
+/**
+ * 构造入站消息文本内容（对齐原版 buildInboundBody）
+ *
+ * 根据消息类型提取文本表示：
+ * - text → text.content
+ * - voice → voice.content 或 "[voice]"
+ * - image → "[image] {url}"
+ * - file → "[file] {url}"
+ * - video → "[video] {url}"
+ * - mixed → 逐项提取拼接
+ * - event → "[event] {eventtype}"
+ * - stream → "[stream_refresh] {id}"
+ *
+ * 如果消息包含 quote（引用），追加引用内容。
+ */
+export declare function buildInboundBody(msg: WebhookInboundMessage): string;
+/**
+ * 格式化引用消息文本（对齐原版 formatQuote）
+ */
+export declare function formatQuote(quote: WebhookInboundQuote): string;
+/** 检查消息是否有媒体内容 */
+export declare function hasMedia(message: WebhookInboundMessage): boolean;
+/**
+ * 构造占位符响应（对齐原版 buildStreamPlaceholderReply）
+ *
+ * 用于 active_new / queued_new 场景：finish=false，显示占位符文本。
+ * 原版规范：第一次回复内容为 "1" 作为最小占位符。
+ */
+export declare function buildStreamPlaceholderReply(streamId: string, placeholderContent?: string): Record<string, unknown>;
+/**
+ * 构造文本占位符响应（对齐原版 buildStreamTextPlaceholderReply）
+ *
+ * 用于 merged 场景：finish=false，显示自定义提示（如"已合并排队处理中..."）。
+ */
+export declare function buildStreamTextPlaceholderReply(streamId: string, content: string): Record<string, unknown>;
+/**
+ * 构造流式响应（从 StreamState 构建）
+ *
+ * 用于 stream_refresh 和 msgid 去重场景：返回当前累积内容 + finish 标记。
+ */
+export declare function buildStreamResponse(stream: StreamState): Record<string, unknown>;