ylib-wecom-openclaw-plugin 2026.4.29

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

@@ -0,0 +1,425 @@
+"use strict";
+/**
+ * WeCom Agent API 客户端
+ * 管理 AccessToken 缓存和 API 调用
+ */
+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.downloadMedia = exports.sendMedia = exports.uploadMedia = exports.sendText = exports.getAccessToken = void 0;
+var node_crypto_1 = __importDefault(require("node:crypto"));
+var constants_js_1 = require("../types/constants.js");
+var http_js_1 = require("../http.js");
+function resolveWecomEgressProxyUrlFromNetwork(network) {
+    return network === null || network === void 0 ? void 0 : network.egressProxyUrl;
+}
+var tokenCaches = new Map();
+function normalizeUploadFilename(filename) {
+    var trimmed = filename.trim();
+    if (!trimmed)
+        return "file.bin";
+    var ext = trimmed.includes(".") ? "." + trimmed.split(".").pop().toLowerCase() : "";
+    var base = ext ? trimmed.slice(0, -ext.length) : trimmed;
+    var sanitizedBase = base
+        .replace(/[^\x20-\x7e]/g, "_")
+        .replace(/["\\\/;=]/g, "_")
+        .replace(/\s+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    var safeBase = sanitizedBase || "file";
+    var safeExt = ext.replace(/[^a-z0-9.]/g, "");
+    return "" + safeBase + (safeExt || ".bin");
+}
+function guessUploadContentType(filename) {
+    var _a;
+    var ext = ((_a = filename.split(".").pop()) === null || _a === void 0 ? void 0 : _a.toLowerCase()) || "";
+    var 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
+ */
+function getAccessToken(agent) {
+    var _a;
+    return __awaiter(this, void 0, void 0, function () {
+        var cacheKey, cache, now;
+        var _this = this;
+        return __generator(this, function (_b) {
+            cacheKey = agent.corpId + ":" + String((_a = agent.agentId) !== null && _a !== void 0 ? _a : "na");
+            cache = tokenCaches.get(cacheKey);
+            if (!cache) {
+                cache = { token: "", expiresAt: 0, refreshPromise: null };
+                tokenCaches.set(cacheKey, cache);
+            }
+            now = Date.now();
+            if (cache.token && cache.expiresAt > now + constants_js_1.LIMITS.TOKEN_REFRESH_BUFFER_MS) {
+                return [2 /*return*/, cache.token];
+            }
+            // 防止并发刷新
+            if (cache.refreshPromise) {
+                return [2 /*return*/, cache.refreshPromise];
+            }
+            cache.refreshPromise = (function () { return __awaiter(_this, void 0, void 0, function () {
+                var url, res, json;
+                var _a;
+                return __generator(this, function (_b) {
+                    switch (_b.label) {
+                        case 0:
+                            _b.trys.push([0, , 3, 4]);
+                            url = constants_js_1.API_ENDPOINTS.GET_TOKEN + "?corpid=" + encodeURIComponent(agent.corpId) + "&corpsecret=" + encodeURIComponent(agent.corpSecret);
+                            return [4 /*yield*/, http_js_1.wecomFetch(url, undefined, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: constants_js_1.LIMITS.REQUEST_TIMEOUT_MS })];
+                        case 1:
+                            res = _b.sent();
+                            return [4 /*yield*/, res.json()];
+                        case 2:
+                            json = _b.sent();
+                            if (!(json === null || json === void 0 ? void 0 : json.access_token)) {
+                                throw new Error("gettoken failed: " + (json === null || json === void 0 ? void 0 : json.errcode) + " " + (json === null || json === void 0 ? void 0 : json.errmsg));
+                            }
+                            cache.token = json.access_token;
+                            cache.expiresAt = Date.now() + ((_a = json.expires_in) !== null && _a !== void 0 ? _a : 7200) * 1000;
+                            return [2 /*return*/, cache.token];
+                        case 3:
+                            cache.refreshPromise = null;
+                            return [7 /*endfinally*/];
+                        case 4: return [2 /*return*/];
+                    }
+                });
+            }); })();
+            return [2 /*return*/, cache.refreshPromise];
+        });
+    });
+}
+exports.getAccessToken = getAccessToken;
+/**
+ * **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 消息内容
+ */
+function sendText(params) {
+    return __awaiter(this, void 0, void 0, function () {
+        var agent, toUser, toParty, toTag, chatId, text, token, useChat, url, body, res, json, details;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    agent = params.agent, toUser = params.toUser, toParty = params.toParty, toTag = params.toTag, chatId = params.chatId, text = params.text;
+                    return [4 /*yield*/, getAccessToken(agent)];
+                case 1:
+                    token = _a.sent();
+                    useChat = Boolean(chatId);
+                    url = useChat
+                        ? constants_js_1.API_ENDPOINTS.SEND_APPCHAT + "?access_token=" + encodeURIComponent(token)
+                        : constants_js_1.API_ENDPOINTS.SEND_MESSAGE + "?access_token=" + encodeURIComponent(token);
+                    body = useChat
+                        ? { chatid: chatId, msgtype: "text", text: { content: text } }
+                        : {
+                            touser: toUser,
+                            toparty: toParty,
+                            totag: toTag,
+                            msgtype: "text",
+                            agentid: requireAgentId(agent),
+                            text: { content: text }
+                        };
+                    return [4 /*yield*/, http_js_1.wecomFetch(url, {
+                            method: "POST",
+                            headers: { "Content-Type": "application/json" },
+                            body: JSON.stringify(body)
+                        }, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: constants_js_1.LIMITS.REQUEST_TIMEOUT_MS })];
+                case 2:
+                    res = _a.sent();
+                    return [4 /*yield*/, res.json()];
+                case 3:
+                    json = _a.sent();
+                    if ((json === null || json === void 0 ? void 0 : json.errcode) !== 0) {
+                        throw new Error("send failed: " + (json === null || json === void 0 ? void 0 : json.errcode) + " " + (json === null || json === void 0 ? void 0 : json.errmsg));
+                    }
+                    if ((json === null || json === void 0 ? void 0 : json.invaliduser) || (json === null || json === void 0 ? void 0 : json.invalidparty) || (json === null || json === void 0 ? void 0 : json.invalidtag)) {
+                        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);
+                    }
+                    return [2 /*return*/];
+            }
+        });
+    });
+}
+exports.sendText = sendText;
+/**
+ * **uploadMedia (上传媒体文件)**
+ *
+ * 上传临时素材到企业微信。
+ * 素材有效期为 3 天。
+ *
+ * @param params.type 媒体类型 (image, voice, video, file)
+ * @param params.buffer 文件二进制数据
+ * @param params.filename 文件名 (需包含正确扩展名)
+ * @returns 媒体 ID (media_id)
+ */
+function uploadMedia(params) {
+    return __awaiter(this, void 0, void 0, function () {
+        var agent, type, buffer, filename, safeFilename, token, proxyUrl, url, uploadOnce, preferredContentType, json;
+        var _this = this;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    agent = params.agent, type = params.type, buffer = params.buffer, filename = params.filename;
+                    safeFilename = normalizeUploadFilename(filename);
+                    return [4 /*yield*/, getAccessToken(agent)];
+                case 1:
+                    token = _a.sent();
+                    proxyUrl = resolveWecomEgressProxyUrlFromNetwork(agent.network);
+                    url = constants_js_1.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");
+                    uploadOnce = function (fileContentType) { return __awaiter(_this, void 0, void 0, function () {
+                        var boundary, header, footer, body, res, json;
+                        return __generator(this, function (_a) {
+                            switch (_a.label) {
+                                case 0:
+                                    boundary = "----WebKitFormBoundary" + node_crypto_1["default"].randomBytes(16).toString("hex");
+                                    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"));
+                                    footer = Buffer.from("\r\n--" + boundary + "--\r\n");
+                                    body = Buffer.concat([header, buffer, footer]);
+                                    console.log("[wecom-upload] Multipart body size=" + body.length + ", boundary=" + boundary + ", fileContentType=" + fileContentType);
+                                    return [4 /*yield*/, http_js_1.wecomFetch(url, {
+                                            method: "POST",
+                                            headers: {
+                                                "Content-Type": "multipart/form-data; boundary=" + boundary,
+                                                "Content-Length": String(body.length)
+                                            },
+                                            body: body
+                                        }, { proxyUrl: proxyUrl, timeoutMs: constants_js_1.LIMITS.REQUEST_TIMEOUT_MS })];
+                                case 1:
+                                    res = _a.sent();
+                                    return [4 /*yield*/, res.json()];
+                                case 2:
+                                    json = _a.sent();
+                                    console.log("[wecom-upload] Response:", JSON.stringify(json));
+                                    return [2 /*return*/, json];
+                            }
+                        });
+                    }); };
+                    preferredContentType = guessUploadContentType(safeFilename);
+                    return [4 /*yield*/, uploadOnce(preferredContentType)];
+                case 2:
+                    json = _a.sent();
+                    if (!(!(json === null || json === void 0 ? void 0 : json.media_id) && preferredContentType !== "application/octet-stream")) return [3 /*break*/, 4];
+                    console.warn("[wecom-upload] Upload failed with " + preferredContentType + ", retrying as application/octet-stream: " + (json === null || json === void 0 ? void 0 : json.errcode) + " " + (json === null || json === void 0 ? void 0 : json.errmsg));
+                    return [4 /*yield*/, uploadOnce("application/octet-stream")];
+                case 3:
+                    json = _a.sent();
+                    _a.label = 4;
+                case 4:
+                    if (!(json === null || json === void 0 ? void 0 : json.media_id)) {
+                        throw new Error("upload failed: " + (json === null || json === void 0 ? void 0 : json.errcode) + " " + (json === null || json === void 0 ? void 0 : json.errmsg));
+                    }
+                    return [2 /*return*/, json.media_id];
+            }
+        });
+    });
+}
+exports.uploadMedia = uploadMedia;
+/**
+ * **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 视频描述 (可选)
+ */
+function sendMedia(params) {
+    return __awaiter(this, void 0, void 0, function () {
+        var agent, toUser, toParty, toTag, chatId, mediaId, mediaType, title, description, token, useChat, url, mediaPayload, body, res, json, details;
+        var _a, _b;
+        return __generator(this, function (_c) {
+            switch (_c.label) {
+                case 0:
+                    agent = params.agent, toUser = params.toUser, toParty = params.toParty, toTag = params.toTag, chatId = params.chatId, mediaId = params.mediaId, mediaType = params.mediaType, title = params.title, description = params.description;
+                    return [4 /*yield*/, getAccessToken(agent)];
+                case 1:
+                    token = _c.sent();
+                    useChat = Boolean(chatId);
+                    url = useChat
+                        ? constants_js_1.API_ENDPOINTS.SEND_APPCHAT + "?access_token=" + encodeURIComponent(token)
+                        : constants_js_1.API_ENDPOINTS.SEND_MESSAGE + "?access_token=" + encodeURIComponent(token);
+                    mediaPayload = mediaType === "video"
+                        ? { media_id: mediaId, title: title !== null && title !== void 0 ? title : "Video", description: description !== null && description !== void 0 ? description : "" }
+                        : { media_id: mediaId };
+                    body = useChat
+                        ? (_a = { chatid: chatId, msgtype: mediaType }, _a[mediaType] = mediaPayload, _a) : (_b = {
+                            touser: toUser,
+                            toparty: toParty,
+                            totag: toTag,
+                            msgtype: mediaType,
+                            agentid: requireAgentId(agent)
+                        },
+                        _b[mediaType] = mediaPayload,
+                        _b);
+                    return [4 /*yield*/, http_js_1.wecomFetch(url, {
+                            method: "POST",
+                            headers: { "Content-Type": "application/json" },
+                            body: JSON.stringify(body)
+                        }, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: constants_js_1.LIMITS.REQUEST_TIMEOUT_MS })];
+                case 2:
+                    res = _c.sent();
+                    return [4 /*yield*/, res.json()];
+                case 3:
+                    json = _c.sent();
+                    if ((json === null || json === void 0 ? void 0 : json.errcode) !== 0) {
+                        throw new Error("send " + mediaType + " failed: " + (json === null || json === void 0 ? void 0 : json.errcode) + " " + (json === null || json === void 0 ? void 0 : json.errmsg));
+                    }
+                    if ((json === null || json === void 0 ? void 0 : json.invaliduser) || (json === null || json === void 0 ? void 0 : json.invalidparty) || (json === null || json === void 0 ? void 0 : json.invalidtag)) {
+                        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);
+                    }
+                    return [2 /*return*/];
+            }
+        });
+    });
+}
+exports.sendMedia = sendMedia;
+/**
+ * **downloadMedia (下载媒体文件)**
+ *
+ * 通过 media_id 从企业微信服务器下载临时素材。
+ *
+ * @returns { buffer, contentType }
+ */
+function downloadMedia(params) {
+    return __awaiter(this, void 0, void 0, function () {
+        var agent, mediaId, token, url, res, contentType, disposition, filename, json, buffer;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    agent = params.agent, mediaId = params.mediaId;
+                    return [4 /*yield*/, getAccessToken(agent)];
+                case 1:
+                    token = _a.sent();
+                    url = constants_js_1.API_ENDPOINTS.DOWNLOAD_MEDIA + "?access_token=" + encodeURIComponent(token) + "&media_id=" + encodeURIComponent(mediaId);
+                    return [4 /*yield*/, http_js_1.wecomFetch(url, undefined, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: constants_js_1.LIMITS.REQUEST_TIMEOUT_MS })];
+                case 2:
+                    res = _a.sent();
+                    if (!res.ok) {
+                        throw new Error("download failed: " + res.status);
+                    }
+                    contentType = res.headers.get("content-type") || "application/octet-stream";
+                    disposition = res.headers.get("content-disposition") || "";
+                    filename = (function () {
+                        // 兼容：filename="a.md" / filename=a.md / filename*=UTF-8''a%2Eb.md
+                        var mStar = disposition.match(/filename\*\s*=\s*([^;]+)/i);
+                        if (mStar) {
+                            var raw = mStar[1].trim().replace(/^"(.*)"$/, "$1");
+                            var parts = raw.split("''");
+                            var encoded = parts.length === 2 ? parts[1] : raw;
+                            try {
+                                return decodeURIComponent(encoded);
+                            }
+                            catch (_a) {
+                                return encoded;
+                            }
+                        }
+                        var m = disposition.match(/filename\s*=\s*([^;]+)/i);
+                        if (!m)
+                            return undefined;
+                        return m[1].trim().replace(/^"(.*)"$/, "$1") || undefined;
+                    })();
+                    if (!contentType.includes("application/json")) return [3 /*break*/, 4];
+                    return [4 /*yield*/, res.json()];
+                case 3:
+                    json = _a.sent();
+                    throw new Error("download failed: " + (json === null || json === void 0 ? void 0 : json.errcode) + " " + (json === null || json === void 0 ? void 0 : json.errmsg));
+                case 4: return [4 /*yield*/, http_js_1.readResponseBodyAsBuffer(res, params.maxBytes)];
+                case 5:
+                    buffer = _a.sent();
+                    return [2 /*return*/, { buffer: buffer, contentType: contentType, filename: filename }];
+            }
+        });
+    });
+}
+exports.downloadMedia = downloadMedia;

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

@@ -0,0 +1,64 @@
+/**
+ * WeCom Agent Webhook 处理器
+ * 处理 XML 格式回调
+ */
+/// <reference types="node" />
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { OpenClawConfig, PluginRuntime } from "ylib-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 declare 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 declare 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>;