ylib-wecom-openclaw-plugin 2026.4.29

package/dist/src/message-parser.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * 企业微信消息内容解析模块
+ *
+ * 负责从 WsFrame 中提取文本、图片、引用等内容
+ */
+var __spreadArrays = (this && this.__spreadArrays) || function () {
+    for (var s = 0, i = 0, il = arguments.length; i < il; i++) s += arguments[i].length;
+    for (var r = Array(s), k = 0, i = 0; i < il; i++)
+        for (var a = arguments[i], j = 0, jl = a.length; j < jl; j++, k++)
+            r[k] = a[j];
+    return r;
+};
+var _a;
+exports.__esModule = true;
+exports.parseMessageContent = void 0;
+// ============================================================================
+// 解析函数
+// ============================================================================
+/**
+ * 将模板卡片事件回调格式化为可继续路由给大模型的文本。
+ *
+ * 这样后续 Agent 可以直接从 question_key / option_id 中理解用户的真实选择。
+ */
+function buildTemplateCardEventText(body) {
+    var _a, _b, _c, _d, _e, _f;
+    var templateCardEvent = (_a = body.event) === null || _a === void 0 ? void 0 : _a.template_card_event;
+    if (body.msgtype !== "event" ||
+        ((_b = body.event) === null || _b === void 0 ? void 0 : _b.eventtype) !== "template_card_event" ||
+        !templateCardEvent) {
+        return undefined;
+    }
+    var selectedItems = (_d = (_c = templateCardEvent.selected_items) === null || _c === void 0 ? void 0 : _c.selected_item) !== null && _d !== void 0 ? _d : [];
+    var selectedLines = selectedItems.map(function (item) {
+        var _a, _b, _c, _d;
+        var questionKey = ((_a = item.question_key) === null || _a === void 0 ? void 0 : _a.trim()) || "unknown_question";
+        var optionIds = (_d = (_c = (_b = item.option_ids) === null || _b === void 0 ? void 0 : _b.option_id) === null || _c === void 0 ? void 0 : _c.filter(Boolean)) !== null && _d !== void 0 ? _d : [];
+        return "- " + questionKey + ": " + (optionIds.length > 0 ? optionIds.join(", ") : "(未选择)");
+    });
+    var senderUserId = ((_e = body.from) === null || _e === void 0 ? void 0 : _e.userid) || "";
+    var senderCorpId = ((_f = body.from) === null || _f === void 0 ? void 0 : _f.corpid) || "";
+    var chatId = body.chatid || senderUserId;
+    return __spreadArrays([
+        "[企业微信模板卡片回调]",
+        "event_type(\u4E8B\u4EF6\u7C7B\u578B): template_card_event",
+        body.msgid ? "msgid(\u6D88\u606F id): " + body.msgid : undefined,
+        body.aibotid ? "aibotid(\u673A\u5668\u4EBA id): " + body.aibotid : undefined,
+        body.chattype ? "chat_type(\u4F1A\u8BDD\u7C7B\u578B): " + body.chattype : undefined,
+        chatId ? "chat_id(\u4F1A\u8BDD id): " + chatId : undefined,
+        senderCorpId ? "from.corpid(\u4F01\u4E1A id): " + senderCorpId : undefined,
+        senderUserId ? "from.userid(\u53D1\u9001\u4EBA id): " + senderUserId : undefined,
+        senderUserId ? "sender_userid(\u53D1\u9001\u4EBA id): " + senderUserId : undefined,
+        templateCardEvent.card_type ? "card_type(\u5361\u7247\u7C7B\u578B): " + templateCardEvent.card_type : undefined,
+        templateCardEvent.event_key ? "event_key(\u4E8B\u4EF6 key): " + templateCardEvent.event_key : undefined,
+        templateCardEvent.task_id ? "task_id(\u4EFB\u52A1 id): " + templateCardEvent.task_id : undefined,
+        selectedLines.length > 0 ? "selected_items(选择项):" : "selected_items(选择项): []"
+    ], selectedLines).filter(function (line) { return Boolean(line); })
+        .join("\n");
+}
+// ============================================================================
+// 权限类型映射
+// ============================================================================
+/** 权限类型枚举 */
+var AuthType;
+(function (AuthType) {
+    /** 新建和编辑文档 */
+    AuthType[AuthType["CREATE_AND_EDIT_DOC"] = 1] = "CREATE_AND_EDIT_DOC";
+    /** 获取成员文档内容 */
+    AuthType[AuthType["GET_DOC_CONTENT"] = 2] = "GET_DOC_CONTENT";
+})(AuthType || (AuthType = {}));
+/** 权限类型值 → 中文描述 */
+var AUTH_TYPE_MAP = (_a = {},
+    _a[AuthType.CREATE_AND_EDIT_DOC] = "新建和编辑文档",
+    _a[AuthType.GET_DOC_CONTENT] = "获取成员文档内容",
+    _a);
+/**
+ * 将权限变更事件回调格式化为可继续路由给大模型的文本。
+ *
+ * 当管理员在授权页面变更权限后，系统收到 auth_change_event 回调，
+ * 根据 auth_list 生成对应的提示文本，引导 Agent 继续操作。
+ */
+function buildAuthChangeEventText(body) {
+    var _a, _b, _c, _d, _e, _f;
+    console.log("authChangeEventCheck", body.event);
+    var authChangeEvent = (_a = body.event) === null || _a === void 0 ? void 0 : _a.auth_change_event;
+    if (body.msgtype !== "event" ||
+        ((_b = body.event) === null || _b === void 0 ? void 0 : _b.eventtype) !== "auth_change_event" ||
+        !authChangeEvent) {
+        return undefined;
+    }
+    var authList = (_c = authChangeEvent.auth_list) !== null && _c !== void 0 ? _c : [];
+    var authDescriptions = authList
+        .map(function (code) { return AUTH_TYPE_MAP[code] || "\u672A\u77E5\u6743\u9650(" + code + ")"; })
+        .join("、");
+    // 根据权限列表内容生成不同的操作指引
+    var hasDocContentAuth = authList.includes(AuthType.GET_DOC_CONTENT);
+    var actionHint;
+    if (hasDocContentAuth) {
+        // 包含"获取成员文档内容"权限，引导 Agent 继续文档操作
+        actionHint = "用户已授予文档内容读取权限，请继续之前的文档操作。";
+    }
+    else if (authList.length > 0) {
+        // 有其他权限但没有文档内容读取权限
+        actionHint = "当前授权不包含文档内容读取权限，无法继续文档操作。请引导用户授予「获取成员文档内容」权限，该权限需要向管理员申请，管理员审批通过后可使用。";
+    }
+    else {
+        // 权限列表为空
+        actionHint = "当前无任何文档权限，无法继续文档操作。请引导用户完成文档授权。";
+    }
+    var senderUserId = ((_d = body.from) === null || _d === void 0 ? void 0 : _d.userid) || "";
+    var senderCorpId = ((_e = body.from) === null || _e === void 0 ? void 0 : _e.corpid) || "";
+    var chatId = ((_f = body.from) === null || _f === void 0 ? void 0 : _f.chat_id) || body.chatid || senderUserId;
+    return [
+        "[企业微信文档权限变更回调]",
+        "event_type(\u4E8B\u4EF6\u7C7B\u578B): auth_change_event",
+        "auth_list(\u5F53\u524D\u6743\u9650\u5217\u8868): [" + authList.join(", ") + "] (" + (authDescriptions || "无") + ")",
+        body.msgid ? "msgid(\u6D88\u606F id): " + body.msgid : undefined,
+        body.aibotid ? "aibotid(\u673A\u5668\u4EBA id): " + body.aibotid : undefined,
+        body.chattype ? "chat_type(\u4F1A\u8BDD\u7C7B\u578B): " + body.chattype : undefined,
+        chatId ? "chat_id(\u4F1A\u8BDD id): " + chatId : undefined,
+        senderCorpId ? "from.corpid(\u4F01\u4E1A id): " + senderCorpId : undefined,
+        senderUserId ? "from.userid(\u53D1\u9001\u4EBA id): " + senderUserId : undefined,
+        "",
+        "[\u64CD\u4F5C\u6307\u5F15] " + actionHint,
+    ]
+        .filter(function (line) { return line !== undefined; })
+        .join("\n");
+}
+/**
+ * 解析消息内容（支持单条消息、图文混排、事件回调和引用消息）
+ * @returns 提取的文本数组、图片URL数组和引用消息内容
+ */
+function parseMessageContent(body) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
+    var textParts = [];
+    var imageUrls = [];
+    var imageAesKeys = new Map();
+    var fileUrls = [];
+    var fileAesKeys = new Map();
+    var quoteContent;
+    if (body.msgtype === "event") {
+        // 处理权限变更事件回调（如文档授权）
+        var authChangeText = buildAuthChangeEventText(body);
+        if (authChangeText) {
+            textParts.push(authChangeText);
+            return { textParts: textParts, imageUrls: imageUrls, imageAesKeys: imageAesKeys, fileUrls: fileUrls, fileAesKeys: fileAesKeys, quoteContent: quoteContent };
+        }
+        // 处理模板卡片事件回调
+        var eventText = buildTemplateCardEventText(body);
+        if (eventText) {
+            textParts.push(eventText);
+        }
+        return { textParts: textParts, imageUrls: imageUrls, imageAesKeys: imageAesKeys, fileUrls: fileUrls, fileAesKeys: fileAesKeys, quoteContent: quoteContent };
+    }
+    // 处理图文混排消息
+    if (body.msgtype === "mixed" && ((_a = body.mixed) === null || _a === void 0 ? void 0 : _a.msg_item)) {
+        for (var _i = 0, _p = body.mixed.msg_item; _i < _p.length; _i++) {
+            var item = _p[_i];
+            if (item.msgtype === "text" && ((_b = item.text) === null || _b === void 0 ? void 0 : _b.content)) {
+                textParts.push(item.text.content);
+            }
+            else if (item.msgtype === "image" && ((_c = item.image) === null || _c === void 0 ? void 0 : _c.url)) {
+                imageUrls.push(item.image.url);
+                if (item.image.aeskey) {
+                    imageAesKeys.set(item.image.url, item.image.aeskey);
+                }
+            }
+        }
+    }
+    else {
+        // 处理单条消息
+        if ((_d = body.text) === null || _d === void 0 ? void 0 : _d.content) {
+            textParts.push(body.text.content);
+        }
+        // 处理语音消息（语音转文字后的文本内容）
+        if (body.msgtype === "voice" && ((_e = body.voice) === null || _e === void 0 ? void 0 : _e.content)) {
+            textParts.push(body.voice.content);
+        }
+        if ((_f = body.image) === null || _f === void 0 ? void 0 : _f.url) {
+            imageUrls.push(body.image.url);
+            if (body.image.aeskey) {
+                imageAesKeys.set(body.image.url, body.image.aeskey);
+            }
+        }
+        // 处理文件消息
+        if (body.msgtype === "file" && ((_g = body.file) === null || _g === void 0 ? void 0 : _g.url)) {
+            fileUrls.push(body.file.url);
+            if (body.file.aeskey) {
+                fileAesKeys.set(body.file.url, body.file.aeskey);
+            }
+        }
+        // 处理视频消息（沿用 file 下载/解密通路，作为文件附件透传）
+        if (body.msgtype === "video" && ((_h = body.video) === null || _h === void 0 ? void 0 : _h.url)) {
+            fileUrls.push(body.video.url);
+            if (body.video.aeskey) {
+                fileAesKeys.set(body.video.url, body.video.aeskey);
+            }
+        }
+    }
+    // 处理引用消息
+    if (body.quote) {
+        if (body.quote.msgtype === "text" && ((_j = body.quote.text) === null || _j === void 0 ? void 0 : _j.content)) {
+            quoteContent = body.quote.text.content;
+        }
+        else if (body.quote.msgtype === "voice" && ((_k = body.quote.voice) === null || _k === void 0 ? void 0 : _k.content)) {
+            quoteContent = body.quote.voice.content;
+        }
+        else if (body.quote.msgtype === "image" && ((_l = body.quote.image) === null || _l === void 0 ? void 0 : _l.url)) {
+            // 引用的图片消息：将图片 URL 加入下载列表
+            imageUrls.push(body.quote.image.url);
+            if (body.quote.image.aeskey) {
+                imageAesKeys.set(body.quote.image.url, body.quote.image.aeskey);
+            }
+        }
+        else if (body.quote.msgtype === "file" && ((_m = body.quote.file) === null || _m === void 0 ? void 0 : _m.url)) {
+            // 引用的文件消息：将文件 URL 加入下载列表
+            fileUrls.push(body.quote.file.url);
+            if (body.quote.file.aeskey) {
+                fileAesKeys.set(body.quote.file.url, body.quote.file.aeskey);
+            }
+        }
+        else if (body.quote.msgtype === "video" && ((_o = body.quote.video) === null || _o === void 0 ? void 0 : _o.url)) {
+            // 引用的视频消息：沿用文件下载通路
+            fileUrls.push(body.quote.video.url);
+            if (body.quote.video.aeskey) {
+                fileAesKeys.set(body.quote.video.url, body.quote.video.aeskey);
+            }
+        }
+    }
+    return { textParts: textParts, imageUrls: imageUrls, imageAesKeys: imageAesKeys, fileUrls: fileUrls, fileAesKeys: fileAesKeys, quoteContent: quoteContent };
+}
+exports.parseMessageContent = parseMessageContent;

package/dist/src/message-sender.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 企业微信消息发送模块
+ *
+ * 负责通过 WSClient 发送回复消息，包含超时保护
+ */
+import type { RuntimeEnv } from "ylib-openclaw/plugin-sdk";
+import { WSClient, WsFrame } from "@wecom/aibot-node-sdk";
+/** 流式回复超时错误码（超过企业微信服务端有效期后，服务端拒绝继续更新） */
+export declare const STREAM_EXPIRED_ERRCODE = 846608;
+/**
+ * 流式回复过期错误
+ * 当服务端返回 errcode=846608 时抛出，表示流式消息已超过企业微信服务端有效期无法更新，
+ * 调用方需降级为主动发送（sendMessage）方式回复。
+ */
+export declare class StreamExpiredError extends Error {
+    readonly errcode = 846608;
+    constructor(message?: string);
+}
+/**
+ * 发送企业微信回复消息
+ * 供 monitor 内部和 channel outbound 使用
+ *
+ * @returns messageId (streamId)
+ */
+export declare function sendWeComReply(params: {
+    wsClient: WSClient;
+    frame: WsFrame;
+    text?: string;
+    runtime: RuntimeEnv;
+    /** 是否为流式回复的最终消息，默认为 true */
+    finish?: boolean;
+    /** 指定 streamId，用于流式回复时保持相同的 streamId */
+    streamId?: string;
+    accountId?: string;
+}): Promise<string>;
+/**
+ * 非阻塞流式文本回复
+ *
+ * 基于 SDK 的 replyStreamNonBlocking 方法：
+ * - 如果上一条同 reqId 的消息尚未收到 ack，则跳过本次发送（返回 'skipped'），
+ *   避免流式中间帧排队积压导致延迟。
+ * - finish=true 的最终帧不受此限制，始终保证发送。
+ *
+ * @returns 'skipped' 表示被跳过，否则返回 streamId
+ */
+export declare function sendWeComReplyNonBlocking(params: {
+    wsClient: WSClient;
+    frame: WsFrame;
+    text: string;
+    runtime: RuntimeEnv;
+    streamId: string;
+    finish?: boolean;
+    accountId?: string;
+}): Promise<string | 'skipped'>;

package/dist/src/message-sender.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * 企业微信消息发送模块
+ *
+ * 负责通过 WSClient 发送回复消息，包含超时保护
+ */
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+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.sendWeComReplyNonBlocking = exports.sendWeComReply = exports.StreamExpiredError = exports.STREAM_EXPIRED_ERRCODE = void 0;
+var aibot_node_sdk_1 = require("@wecom/aibot-node-sdk");
+var const_js_1 = require("./const.js");
+var timeout_js_1 = require("./timeout.js");
+var im_runtime_telemetry_js_1 = require("./im-runtime-telemetry.js");
+var proactive_markdown_send_js_1 = require("./proactive-markdown-send.js");
+// ============================================================================
+// 流式过期错误（errcode 846608）
+// ============================================================================
+/** 流式回复超时错误码（超过企业微信服务端有效期后，服务端拒绝继续更新） */
+exports.STREAM_EXPIRED_ERRCODE = 846608;
+/**
+ * 流式回复过期错误
+ * 当服务端返回 errcode=846608 时抛出，表示流式消息已超过企业微信服务端有效期无法更新，
+ * 调用方需降级为主动发送（sendMessage）方式回复。
+ */
+var StreamExpiredError = /** @class */ (function (_super) {
+    __extends(StreamExpiredError, _super);
+    function StreamExpiredError(message) {
+        var _this = _super.call(this, message !== null && message !== void 0 ? message : "Stream message update expired (errcode=" + exports.STREAM_EXPIRED_ERRCODE + ")") || this;
+        _this.errcode = exports.STREAM_EXPIRED_ERRCODE;
+        _this.name = "StreamExpiredError";
+        return _this;
+    }
+    return StreamExpiredError;
+}(Error));
+exports.StreamExpiredError = StreamExpiredError;
+// ============================================================================
+// 消息发送
+// ============================================================================
+/**
+ * 发送企业微信回复消息
+ * 供 monitor 内部和 channel outbound 使用
+ *
+ * @returns messageId (streamId)
+ */
+function sendWeComReply(params) {
+    var _a, _b, _c, _d, _e;
+    return __awaiter(this, void 0, void 0, function () {
+        var wsClient, frame, text, runtime, _f, finish, existingStreamId, accountId, streamId, body, chatId, err_1, errMsg;
+        return __generator(this, function (_g) {
+            switch (_g.label) {
+                case 0:
+                    wsClient = params.wsClient, frame = params.frame, text = params.text, runtime = params.runtime, _f = params.finish, finish = _f === void 0 ? true : _f, existingStreamId = params.streamId, accountId = params.accountId;
+                    if (!text) {
+                        return [2 /*return*/, ""];
+                    }
+                    streamId = existingStreamId || aibot_node_sdk_1.generateReqId("stream");
+                    if (!wsClient.isConnected) {
+                        (_a = runtime.error) === null || _a === void 0 ? void 0 : _a.call(runtime, "[wecom] WSClient not connected, cannot send reply");
+                        throw new Error("WSClient not connected");
+                    }
+                    body = frame.body;
+                    if (!(body.msgtype === "event")) return [3 /*break*/, 2];
+                    // 中间帧（thinking / 流式增量）直接跳过，仅在最终帧主动发一次文本。
+                    if (!finish) {
+                        (_b = runtime.log) === null || _b === void 0 ? void 0 : _b.call(runtime, "[plugin -> server] skip non-final stream for event callback, streamId=" + streamId);
+                        return [2 /*return*/, streamId];
+                    }
+                    chatId = body.chatid || ((_c = body.from) === null || _c === void 0 ? void 0 : _c.userid);
+                    if (!chatId) {
+                        throw new Error("Missing chatId for event callback reply");
+                    }
+                    return [4 /*yield*/, proactive_markdown_send_js_1.sendWeComMarkdownMessageChunks({
+                            wsClient: wsClient,
+                            chatId: chatId,
+                            text: text,
+                            runtime: runtime,
+                            accountId: accountId,
+                            label: "event-active-send",
+                            timeoutMs: const_js_1.REPLY_SEND_TIMEOUT_MS
+                        })];
+                case 1:
+                    _g.sent();
+                    (_d = runtime.log) === null || _d === void 0 ? void 0 : _d.call(runtime, "[plugin -> server] event-active-send chatId=" + chatId + ", finish=" + finish);
+                    return [2 /*return*/, streamId];
+                case 2:
+                    _g.trys.push([2, 4, , 5]);
+                    return [4 /*yield*/, timeout_js_1.withTimeout(wsClient.replyStream(frame, streamId, text, finish), const_js_1.REPLY_SEND_TIMEOUT_MS, "Reply send timed out (streamId=" + streamId + ")")];
+                case 3:
+                    _g.sent();
+                    return [3 /*break*/, 5];
+                case 4:
+                    err_1 = _g.sent();
+                    errMsg = (err_1 === null || err_1 === void 0 ? void 0 : err_1.errmsg) || (err_1 === null || err_1 === void 0 ? void 0 : err_1.message) || String(err_1);
+                    if ((err_1 === null || err_1 === void 0 ? void 0 : err_1.errcode) === exports.STREAM_EXPIRED_ERRCODE ||
+                        errMsg.includes(String(exports.STREAM_EXPIRED_ERRCODE))) {
+                        throw new StreamExpiredError(errMsg);
+                    }
+                    throw err_1;
+                case 5:
+                    if (accountId) {
+                        im_runtime_telemetry_js_1.imRuntimeRecordChannelActivity("wecom", accountId, "outbound");
+                    }
+                    (_e = runtime.log) === null || _e === void 0 ? void 0 : _e.call(runtime, "[plugin -> server] streamId=" + streamId + ", finish=" + finish);
+                    return [2 /*return*/, streamId];
+            }
+        });
+    });
+}
+exports.sendWeComReply = sendWeComReply;
+// ============================================================================
+// 非阻塞流式发送（用于 onPartialReply 场景）
+// ============================================================================
+/**
+ * 非阻塞流式文本回复
+ *
+ * 基于 SDK 的 replyStreamNonBlocking 方法：
+ * - 如果上一条同 reqId 的消息尚未收到 ack，则跳过本次发送（返回 'skipped'），
+ *   避免流式中间帧排队积压导致延迟。
+ * - finish=true 的最终帧不受此限制，始终保证发送。
+ *
+ * @returns 'skipped' 表示被跳过，否则返回 streamId
+ */
+function sendWeComReplyNonBlocking(params) {
+    return __awaiter(this, void 0, void 0, function () {
+        var wsClient, frame, text, runtime, streamId, _a, finish, accountId, result, err_2, errMsg;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    wsClient = params.wsClient, frame = params.frame, text = params.text, runtime = params.runtime, streamId = params.streamId, _a = params.finish, finish = _a === void 0 ? false : _a, accountId = params.accountId;
+                    if (!text) {
+                        return [2 /*return*/, 'skipped'];
+                    }
+                    if (!wsClient.isConnected) {
+                        return [2 /*return*/, 'skipped'];
+                    }
+                    _b.label = 1;
+                case 1:
+                    _b.trys.push([1, 3, , 4]);
+                    return [4 /*yield*/, wsClient.replyStreamNonBlocking(frame, streamId, text, finish)];
+                case 2:
+                    result = _b.sent();
+                    if (result === 'skipped') {
+                        return [2 /*return*/, 'skipped'];
+                    }
+                    if (accountId) {
+                        im_runtime_telemetry_js_1.imRuntimeRecordChannelActivity("wecom", accountId, "outbound");
+                    }
+                    return [2 /*return*/, streamId];
+                case 3:
+                    err_2 = _b.sent();
+                    errMsg = (err_2 === null || err_2 === void 0 ? void 0 : err_2.errmsg) || (err_2 === null || err_2 === void 0 ? void 0 : err_2.message) || String(err_2);
+                    if ((err_2 === null || err_2 === void 0 ? void 0 : err_2.errcode) === exports.STREAM_EXPIRED_ERRCODE ||
+                        errMsg.includes(String(exports.STREAM_EXPIRED_ERRCODE))) {
+                        throw new StreamExpiredError(errMsg);
+                    }
+                    throw err_2;
+                case 4: return [2 /*return*/];
+            }
+        });
+    });
+}
+exports.sendWeComReplyNonBlocking = sendWeComReplyNonBlocking;

package/dist/src/monitor.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 企业微信 WebSocket 监控器主模块
+ *
+ * 负责：
+ * - 建立和管理 WebSocket 连接
+ * - 协调消息处理流程（解析→策略检查→下载图片→路由回复）
+ * - 资源生命周期管理
+ *
+ * 子模块：
+ * - message-parser.ts  : 消息内容解析
+ * - message-sender.ts  : 消息发送（带超时保护）
+ * - media-handler.ts   : 图片下载和保存（带超时保护）
+ * - group-policy.ts    : 群组访问控制
+ * - dm-policy.ts       : 私聊访问控制
+ * - state-manager.ts   : 全局状态管理（带 TTL 清理）
+ * - timeout.ts         : 超时工具
+ */
+import { WSClient } from "@wecom/aibot-node-sdk";
+import type { WsFrame } from "@wecom/aibot-node-sdk";
+import type { RuntimeEnv } from "ylib-openclaw/plugin-sdk";
+import type { WeComMonitorOptions, MessageState } from "./interface.js";
+import type { ResolvedWeComAccount } from "./utils.js";
+export type { WeComMonitorOptions } from "./interface.js";
+export { WeComCommand } from "./const.js";
+export { getWeComWebSocket, setReqIdForChat, getReqIdForChatAsync, getReqIdForChat, deleteReqIdForChat, warmupReqIdStore, flushReqIdStore, } from "./state-manager.js";
+export { sendWeComReply } from "./message-sender.js";
+/** deliver 回调所需的上下文 */
+interface DeliverContext {
+    wsClient: WSClient;
+    frame: WsFrame;
+    state: MessageState;
+    account: ResolvedWeComAccount;
+    runtime: RuntimeEnv;
+}
+declare function isStreamReplyLocallyExpired(state: MessageState, now?: number): boolean;
+declare function markStreamReplyLocallyExpired(state: MessageState, runtime: RuntimeEnv, reason: string): boolean;
+/**
+ * 关闭 thinking 流（发送 finish=true 的流式消息）
+ *
+ * thinking 是通过 replyStream 用 streamId 发的流式消息，
+ * 只有同一 streamId 的 replyStream(finish=true) 才能关闭它。
+ *
+ * ⚠️ 注意：企微会忽略空格等不可见内容，必须用有可见字符的文案才能真正
+ *    替换掉 thinking 动画，否则 thinking 会一直残留。
+ *
+ * 关闭策略（按优先级）：
+ * 1. 有可见文本 → 用完整文本关闭
+ * 2. 有模板卡片发送成功 → "📋 卡片消息已发送。"
+ * 3. 有媒体成功发送（通过 deliver 回调） → 用友好提示"文件已发送"
+ * 4. 媒体发送失败 → 直接用错误摘要替换 thinking
+ *
+ * 降级策略：
+ * - 当 streamExpired=true（errcode 846608 或本地 TTL 保护触发）时，流式通道不可用，
+ *   改用 wsClient.sendMessage 主动发送完整文本。
+ *
+ * 注意：模板卡片的检测和发送已在 finishThinkingStream 之前由
+ *       processTemplateCardsIfNeeded 完成，此处只关心最后的消息发送。
+ */
+declare function finishThinkingStream(ctx: DeliverContext): Promise<void>;
+/**
+ * 监听企业微信 WebSocket 连接
+ * 使用 aibot-node-sdk 简化连接管理
+ */
+export declare function monitorWeComProvider(options: WeComMonitorOptions): Promise<void>;
+export declare const __monitorTestables: {
+    finishThinkingStream: typeof finishThinkingStream;
+    isStreamReplyLocallyExpired: typeof isStreamReplyLocallyExpired;
+    markStreamReplyLocallyExpired: typeof markStreamReplyLocallyExpired;
+};