ylib-wecom-openclaw-plugin 2026.4.29

package/dist/src/timeout.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 超时控制工具模块
+ *
+ * 为异步操作提供统一的超时保护机制
+ */
+/**
+ * 为 Promise 添加超时保护
+ *
+ * @param promise - 原始 Promise
+ * @param timeoutMs - 超时时间（毫秒）
+ * @param message - 超时错误消息
+ * @returns 带超时保护的 Promise
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message?: string): Promise<T>;
+/**
+ * 超时错误类型
+ */
+export declare class TimeoutError extends Error {
+    constructor(message: string);
+}

package/dist/src/timeout.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * 超时控制工具模块
+ *
+ * 为异步操作提供统一的超时保护机制
+ */
+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 __());
+    };
+})();
+exports.__esModule = true;
+exports.TimeoutError = exports.withTimeout = void 0;
+/**
+ * 为 Promise 添加超时保护
+ *
+ * @param promise - 原始 Promise
+ * @param timeoutMs - 超时时间（毫秒）
+ * @param message - 超时错误消息
+ * @returns 带超时保护的 Promise
+ */
+function withTimeout(promise, timeoutMs, message) {
+    if (timeoutMs <= 0 || !Number.isFinite(timeoutMs)) {
+        return promise;
+    }
+    var timeoutId;
+    var timeoutPromise = new Promise(function (_, reject) {
+        timeoutId = setTimeout(function () {
+            reject(new TimeoutError(message !== null && message !== void 0 ? message : "Operation timed out after " + timeoutMs + "ms"));
+        }, timeoutMs);
+    });
+    return Promise.race([promise, timeoutPromise])["finally"](function () {
+        clearTimeout(timeoutId);
+    });
+}
+exports.withTimeout = withTimeout;
+/**
+ * 超时错误类型
+ */
+var TimeoutError = /** @class */ (function (_super) {
+    __extends(TimeoutError, _super);
+    function TimeoutError(message) {
+        var _this = _super.call(this, message) || this;
+        _this.name = "TimeoutError";
+        return _this;
+    }
+    return TimeoutError;
+}(Error));
+exports.TimeoutError = TimeoutError;

package/dist/src/types/account.d.ts

@@ -0,0 +1,29 @@
+/**
+ * WeCom 账号类型定义
+ */
+import type { WecomAgentConfig, WecomNetworkConfig } from "./config.js";
+/**
+ * 解析后的 Agent 账号
+ */
+export declare type ResolvedAgentAccount = {
+    /** 账号 ID */
+    accountId: string;
+    /** 是否启用 */
+    enabled: boolean;
+    /** 是否配置完整 */
+    configured: boolean;
+    /** 企业 ID */
+    corpId: string;
+    /** 应用 Secret */
+    corpSecret: string;
+    /** 应用 ID (数字，可选) */
+    agentId?: number;
+    /** 回调 Token */
+    token: string;
+    /** 回调加密密钥 */
+    encodingAESKey: string;
+    /** 原始配置 */
+    config: WecomAgentConfig;
+    /** 网络配置（来自 channels.wecom.network） */
+    network?: WecomNetworkConfig;
+};

package/dist/src/types/account.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * WeCom 账号类型定义
+ */
+exports.__esModule = true;

package/dist/src/types/config.d.ts

@@ -0,0 +1,98 @@
+/**
+ * WeCom 子模块配置类型定义
+ *
+ * 注意：顶层配置类型 WeComConfig 定义在 src/utils.ts 中，以平铺结构为准。
+ * 本文件仅定义 Agent/Bot/DM/Network/Media 等子模块的配置类型。
+ */
+/** 媒体处理配置 */
+export declare type WecomMediaConfig = {
+    /** 临时文件目录（未配置时使用系统临时目录）。 */
+    tempDir?: string;
+    /** 媒体临时文件保留时长（小时）。 */
+    retentionHours?: number;
+    /** 启动时是否清理过期临时文件。 */
+    cleanupOnStart?: boolean;
+    /** 入站/下载媒体大小上限（字节）。 */
+    maxBytes?: number;
+};
+/** 网络配置 */
+export declare type WecomNetworkConfig = {
+    /** HTTP 请求超时时间（毫秒）。 */
+    timeoutMs?: number;
+    /** 网络请求重试次数。 */
+    retries?: number;
+    /** 网络请求重试间隔（毫秒）。 */
+    retryDelayMs?: number;
+    /**
+     * 出口代理（用于企业可信 IP 固定出口场景）。
+     * 示例: "http://proxy.company.local:3128"
+     */
+    egressProxyUrl?: string;
+};
+/**
+ * Bot 模式配置 (智能体)
+ * 用于接收 JSON 格式回调 + 流式回复
+ */
+export declare type WecomBotConfig = {
+    /** 智能机器人 ID（用于 Matrix 模式二次身份确认，webhook 模式） */
+    aibotid?: string;
+    /** 回调 Token (企微后台生成，webhook 模式必填) */
+    token?: string;
+    /** 回调加密密钥 (企微后台生成，webhook 模式必填) */
+    encodingAESKey?: string;
+    /**
+     * BotId 列表（可选，用于审计与告警）。
+     * - 回调路由优先由 URL + 签名决定；botIds 不参与强制拦截。
+     * - 当解密后的 aibotid 不在 botIds 中时，仅记录告警日志。
+     */
+    botIds?: string[];
+    /** 接收者 ID (可选，用于解密校验) */
+    receiveId?: string;
+    /** 流式消息占位符 */
+    streamPlaceholderContent?: string;
+    /** 欢迎语 */
+    welcomeText?: string;
+    /** DM 策略: 'open' 允许所有人, 'pairing' 需要配对, 'allowlist' 仅允许列表, 'disabled' 禁用 */
+    dmPolicy?: 'open' | 'pairing' | 'allowlist' | 'disabled';
+    /** 允许的用户列表，为空表示允许所有人 */
+    allowFrom?: Array<string | number>;
+    /** 连接模式：固定 websocket（管理端只读；保留 webhook 仅用于历史兼容解析） */
+    connectionMode?: 'webhook' | 'websocket';
+    /** 机器人 BotID（websocket 模式必填，企微后台获取） */
+    botId?: string;
+    /** 机器人 Secret（websocket 模式必填，企微后台获取） */
+    secret?: string;
+};
+/**
+ * Agent 模式配置 (自建应用)
+ * 用于接收 XML 格式回调 + API 主动发送
+ */
+export declare type WecomAgentConfig = {
+    /** 企业 ID */
+    corpId: string;
+    /** 应用 Secret */
+    corpSecret: string;
+    /** 应用 ID（可选；不填时可接收回调，但主动发送需具备该字段） */
+    agentId?: number | string;
+    /** 回调 Token (企微后台「设置API接收」) */
+    token: string;
+    /** 回调加密密钥 (企微后台「设置API接收」) */
+    encodingAESKey: string;
+    /** 欢迎语 */
+    welcomeText?: string;
+    /** DM 策略: 'open' 允许所有人, 'pairing' 需要配对, 'allowlist' 仅允许列表, 'disabled' 禁用 */
+    dmPolicy?: 'open' | 'pairing' | 'allowlist' | 'disabled';
+    /** 允许的用户列表，为空表示允许所有人 */
+    allowFrom?: Array<string | number>;
+};
+/** 动态 Agent 配置 */
+export declare type WecomDynamicAgentsConfig = {
+    /** 是否启用动态 Agent */
+    enabled?: boolean;
+    /** 私聊：是否为每个用户创建独立 Agent */
+    dmCreateAgent?: boolean;
+    /** 群聊：是否启用动态 Agent */
+    groupEnabled?: boolean;
+    /** 管理员列表（绕过动态路由，使用主 Agent） */
+    adminUsers?: string[];
+};

package/dist/src/types/config.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * WeCom 子模块配置类型定义
+ *
+ * 注意：顶层配置类型 WeComConfig 定义在 src/utils.ts 中，以平铺结构为准。
+ * 本文件仅定义 Agent/Bot/DM/Network/Media 等子模块的配置类型。
+ */
+exports.__esModule = true;

package/dist/src/types/constants.d.ts

@@ -0,0 +1,42 @@
+/**
+ * WeCom 双模式常量定义
+ */
+/** 固定 Webhook 路径 */
+export declare const WEBHOOK_PATHS: {
+    /** Bot 模式历史兼容路径（不再维护） */
+    readonly BOT: "/wecom";
+    /** Bot 模式历史备用兼容路径（不再维护） */
+    readonly BOT_ALT: "/wecom/bot";
+    /** Agent 模式历史兼容路径（不再维护） */
+    readonly AGENT: "/wecom/agent";
+    /** Bot 模式推荐路径前缀 */
+    readonly BOT_PLUGIN: "/plugins/wecom/bot";
+    /** Agent 模式推荐路径前缀 */
+    readonly AGENT_PLUGIN: "/plugins/wecom/agent";
+};
+/** 企业微信 API 端点 */
+export declare const API_ENDPOINTS: {
+    readonly GET_TOKEN: "https://qyapi.weixin.qq.com/cgi-bin/gettoken";
+    readonly SEND_MESSAGE: "https://qyapi.weixin.qq.com/cgi-bin/message/send";
+    readonly SEND_APPCHAT: "https://qyapi.weixin.qq.com/cgi-bin/appchat/send";
+    readonly UPLOAD_MEDIA: "https://qyapi.weixin.qq.com/cgi-bin/media/upload";
+    readonly DOWNLOAD_MEDIA: "https://qyapi.weixin.qq.com/cgi-bin/media/get";
+};
+/** 各类限制常量 */
+export declare const LIMITS: {
+    /** 文本消息最大字节数 */
+    readonly TEXT_MAX_BYTES: 2048;
+    /** Token 刷新缓冲时间 (提前刷新) */
+    readonly TOKEN_REFRESH_BUFFER_MS: 60000;
+    /** HTTP 请求超时 */
+    readonly REQUEST_TIMEOUT_MS: 15000;
+    /** 最大请求体大小 */
+    readonly MAX_REQUEST_BODY_SIZE: number;
+};
+/** AES 加密常量 */
+export declare const CRYPTO: {
+    /** PKCS#7 块大小 */
+    readonly PKCS7_BLOCK_SIZE: 32;
+    /** AES Key 长度 */
+    readonly AES_KEY_LENGTH: 32;
+};

package/dist/src/types/constants.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * WeCom 双模式常量定义
+ */
+exports.__esModule = true;
+exports.CRYPTO = exports.LIMITS = exports.API_ENDPOINTS = exports.WEBHOOK_PATHS = void 0;
+/** 固定 Webhook 路径 */
+exports.WEBHOOK_PATHS = {
+    /** Bot 模式历史兼容路径（不再维护） */
+    BOT: "/wecom",
+    /** Bot 模式历史备用兼容路径（不再维护） */
+    BOT_ALT: "/wecom/bot",
+    /** Agent 模式历史兼容路径（不再维护） */
+    AGENT: "/wecom/agent",
+    /** Bot 模式推荐路径前缀 */
+    BOT_PLUGIN: "/plugins/wecom/bot",
+    /** Agent 模式推荐路径前缀 */
+    AGENT_PLUGIN: "/plugins/wecom/agent"
+};
+/** 企业微信 API 端点 */
+exports.API_ENDPOINTS = {
+    GET_TOKEN: "https://qyapi.weixin.qq.com/cgi-bin/gettoken",
+    SEND_MESSAGE: "https://qyapi.weixin.qq.com/cgi-bin/message/send",
+    SEND_APPCHAT: "https://qyapi.weixin.qq.com/cgi-bin/appchat/send",
+    UPLOAD_MEDIA: "https://qyapi.weixin.qq.com/cgi-bin/media/upload",
+    DOWNLOAD_MEDIA: "https://qyapi.weixin.qq.com/cgi-bin/media/get"
+};
+/** 各类限制常量 */
+exports.LIMITS = {
+    /** 文本消息最大字节数 */
+    TEXT_MAX_BYTES: 2048,
+    /** Token 刷新缓冲时间 (提前刷新) */
+    TOKEN_REFRESH_BUFFER_MS: 60000,
+    /** HTTP 请求超时 */
+    REQUEST_TIMEOUT_MS: 15000,
+    /** 最大请求体大小 */
+    MAX_REQUEST_BODY_SIZE: 1024 * 1024
+};
+/** AES 加密常量 */
+exports.CRYPTO = {
+    /** PKCS#7 块大小 */
+    PKCS7_BLOCK_SIZE: 32,
+    /** AES Key 长度 */
+    AES_KEY_LENGTH: 32
+};

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

@@ -0,0 +1,7 @@
+/**
+ * WeCom 类型统一导出
+ */
+export * from "./constants.js";
+export type { WecomMediaConfig, WecomNetworkConfig, WecomBotConfig, WecomAgentConfig, } from "./config.js";
+export type { ResolvedAgentAccount, } from "./account.js";
+export type { WecomBotInboundBase, WecomBotInboundText, WecomBotInboundVoice, WecomBotInboundVideo, WecomBotInboundStreamRefresh, WecomBotInboundEvent, WecomBotInboundMessage, WecomAgentInboundMessage, WecomInboundQuote, WecomTemplateCard, WecomOutboundMessage, } from "./message.js";

package/dist/src/types/index.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * WeCom 类型统一导出
+ */
+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];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !exports.hasOwnProperty(p)) __createBinding(exports, m, p);
+};
+exports.__esModule = true;
+// 常量
+__exportStar(require("./constants.js"), exports);

package/dist/src/types/message.d.ts

@@ -0,0 +1,238 @@
+/**
+ * WeCom 消息类型定义
+ * Bot 和 Agent 模式共用
+ */
+/**
+ * Bot 模式入站消息基础结构 (JSON)
+ */
+/**
+ * **WecomBotInboundBase (Bot 入站消息基类)**
+ *
+ * Bot 模式下 JSON 格式回调的基础字段。
+ * @property msgid 消息 ID
+ * @property aibotid 机器人 ID
+ * @property chattype 会话类型: "single" | "group"
+ * @property chatid 群聊 ID (仅群组时存在)
+ * @property response_url 下行回复 URL (用于被动响应转主动推送)
+ * @property from 发送者信息
+ */
+export declare type WecomBotInboundBase = {
+    msgid?: string;
+    aibotid?: string;
+    chattype?: "single" | "group";
+    chatid?: string;
+    response_url?: string;
+    from?: {
+        userid?: string;
+        corpid?: string;
+    };
+    msgtype?: string;
+    /** 附件数量 (部分消息存在) */
+    attachment_count?: number;
+};
+export declare type WecomBotInboundText = WecomBotInboundBase & {
+    msgtype: "text";
+    text?: {
+        content?: string;
+    };
+    quote?: WecomInboundQuote;
+};
+export declare type WecomBotInboundVoice = WecomBotInboundBase & {
+    msgtype: "voice";
+    voice?: {
+        content?: string;
+    };
+    quote?: WecomInboundQuote;
+};
+export declare type WecomBotInboundVideo = WecomBotInboundBase & {
+    msgtype: "video";
+    video?: {
+        url?: string;
+        aeskey?: string;
+    };
+    quote?: WecomInboundQuote;
+};
+export declare type WecomBotInboundStreamRefresh = WecomBotInboundBase & {
+    msgtype: "stream";
+    stream?: {
+        id?: string;
+    };
+};
+export declare type WecomBotInboundEvent = WecomBotInboundBase & {
+    msgtype: "event";
+    create_time?: number;
+    event?: {
+        eventtype?: string;
+        [key: string]: unknown;
+    };
+};
+/**
+ * **WecomInboundQuote (引用消息)**
+ *
+ * 消息中引用的原始内容（如回复某条消息）。
+ * 支持引用文本、图片、混合类型、语音、文件等。
+ */
+export declare type WecomInboundQuote = {
+    msgtype?: "text" | "image" | "mixed" | "voice" | "file" | "video";
+    /** 引用文本内容 */
+    text?: {
+        content?: string;
+    };
+    /** 引用图片 URL */
+    image?: {
+        url?: string;
+    };
+    /** 引用混合消息 (图文) */
+    mixed?: {
+        msg_item?: Array<{
+            msgtype: "text" | "image";
+            text?: {
+                content?: string;
+            };
+            image?: {
+                url?: string;
+            };
+        }>;
+    };
+    /** 引用语音 */
+    voice?: {
+        content?: string;
+    };
+    /** 引用文件 */
+    file?: {
+        url?: string;
+    };
+    /** 引用视频 */
+    video?: {
+        url?: string;
+    };
+};
+export declare type WecomBotInboundMessage = WecomBotInboundText | WecomBotInboundVoice | WecomBotInboundVideo | WecomBotInboundStreamRefresh | WecomBotInboundEvent | (WecomBotInboundBase & {
+    quote?: WecomInboundQuote;
+} & Record<string, unknown>);
+/**
+ * Agent 模式入站消息结构 (解析自 XML)
+ */
+/**
+ * **WecomAgentInboundMessage (Agent 入站消息)**
+ *
+ * Agent 模式下解析自 XML 的扁平化消息结构。
+ * 键名保持 PascalCase (如 `ToUserName`)。
+ */
+export declare type WecomAgentInboundMessage = {
+    ToUserName?: string;
+    FromUserName?: string;
+    CreateTime?: number;
+    MsgType?: string;
+    MsgId?: string;
+    AgentID?: number;
+    Content?: string;
+    PicUrl?: string;
+    MediaId?: string;
+    FileName?: string;
+    Format?: string;
+    Recognition?: string;
+    ThumbMediaId?: string;
+    Location_X?: number;
+    Location_Y?: number;
+    Scale?: number;
+    Label?: string;
+    Title?: string;
+    Description?: string;
+    Url?: string;
+    Event?: string;
+    EventKey?: string;
+    ChatId?: string;
+};
+/**
+ * 模板卡片类型
+ */
+/**
+ * **WecomTemplateCard (模板卡片)**
+ *
+ * 复杂的交互式卡片结构。
+ * @property card_type 卡片类型: "text_notice" | "news_notice" | "button_interaction" ...
+ * @property source 来源信息
+ * @property main_title 主标题
+ * @property sub_title_text 副标题
+ * @property horizontal_content_list 水平排列的键值列表
+ * @property button_list 按钮列表
+ */
+export declare type WecomTemplateCard = {
+    card_type: "text_notice" | "news_notice" | "button_interaction" | "vote_interaction" | "multiple_interaction";
+    source?: {
+        icon_url?: string;
+        desc?: string;
+        desc_color?: number;
+    };
+    main_title?: {
+        title?: string;
+        desc?: string;
+    };
+    task_id?: string;
+    button_list?: Array<{
+        text: string;
+        style?: number;
+        key: string;
+    }>;
+    sub_title_text?: string;
+    horizontal_content_list?: Array<{
+        keyname: string;
+        value?: string;
+        type?: number;
+        url?: string;
+        userid?: string;
+    }>;
+    card_action?: {
+        type: number;
+        url?: string;
+        appid?: string;
+        pagepath?: string;
+    };
+    action_menu?: {
+        desc: string;
+        action_list: Array<{
+            text: string;
+            key: string;
+        }>;
+    };
+    select_list?: Array<{
+        question_key: string;
+        title?: string;
+        selected_id?: string;
+        option_list: Array<{
+            id: string;
+            text: string;
+        }>;
+    }>;
+    submit_button?: {
+        text: string;
+        key: string;
+    };
+    checkbox?: {
+        question_key: string;
+        option_list: Array<{
+            id: string;
+            text: string;
+            is_checked?: boolean;
+        }>;
+        mode?: number;
+    };
+};
+/**
+ * 出站消息类型
+ */
+export declare type WecomOutboundMessage = {
+    msgtype: "text";
+    text: {
+        content: string;
+    };
+} | {
+    msgtype: "markdown";
+    markdown: {
+        content: string;
+    };
+} | {
+    msgtype: "template_card";
+    template_card: WecomTemplateCard;
+};

package/dist/src/types/message.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * WeCom 消息类型定义
+ * Bot 和 Agent 模式共用
+ */
+exports.__esModule = true;