@wecom/wecom-openclaw-plugin 1.0.0

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

@@ -0,0 +1,72 @@
+/**
+ * 企业微信消息内容解析模块
+ *
+ * 负责从 WsFrame 中提取文本、图片、引用等内容
+ */
+export interface MessageBody {
+    msgid: string;
+    aibotid?: string;
+    chatid?: string;
+    chattype: "single" | "group";
+    from: {
+        userid: string;
+    };
+    response_url?: string;
+    msgtype: string;
+    text?: {
+        content: string;
+    };
+    image?: {
+        url?: string;
+        aeskey?: string;
+    };
+    voice?: {
+        content?: string;
+    };
+    mixed?: {
+        msg_item: Array<{
+            msgtype: "text" | "image";
+            text?: {
+                content: string;
+            };
+            image?: {
+                url?: string;
+                aeskey?: string;
+            };
+        }>;
+    };
+    file?: {
+        url?: string;
+        aeskey?: string;
+    };
+    quote?: {
+        msgtype: string;
+        text?: {
+            content: string;
+        };
+        voice?: {
+            content: string;
+        };
+        image?: {
+            url?: string;
+            aeskey?: string;
+        };
+        file?: {
+            url?: string;
+            aeskey?: string;
+        };
+    };
+}
+export interface ParsedMessageContent {
+    textParts: string[];
+    imageUrls: string[];
+    imageAesKeys: Map<string, string>;
+    fileUrls: string[];
+    fileAesKeys: Map<string, string>;
+    quoteContent: string | undefined;
+}
+/**
+ * 解析消息内容（支持单条消息、图文混排和引用消息）
+ * @returns 提取的文本数组、图片URL数组和引用消息内容
+ */
+export declare function parseMessageContent(body: MessageBody): ParsedMessageContent;

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

@@ -0,0 +1,23 @@
+/**
+ * 企业微信消息发送模块
+ *
+ * 负责通过 WSClient 发送回复消息，包含超时保护
+ */
+import type { RuntimeEnv } from "openclaw/plugin-sdk";
+import type { WSClient, WsFrame } from "@wecom/aibot-node-sdk";
+/**
+ * 发送企业微信回复消息
+ * 供 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;
+}): Promise<string>;

package/dist/src/monitor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 企业微信 WebSocket 监控器主模块
+ *
+ * 负责：
+ * - 建立和管理 WebSocket 连接
+ * - 协调消息处理流程（解析→策略检查→下载图片→路由回复）
+ * - 资源生命周期管理
+ *
+ * 子模块：
+ * - message-parser.ts  : 消息内容解析
+ * - message-sender.ts  : 消息发送（带超时保护）
+ * - media-handler.ts   : 图片下载和保存（带超时保护）
+ * - group-policy.ts    : 群组访问控制
+ * - dm-policy.ts       : 私聊访问控制
+ * - state-manager.ts   : 全局状态管理（带 TTL 清理）
+ * - timeout.ts         : 超时工具
+ */
+import type { WeComMonitorOptions } from "./interface.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";
+/**
+ * 监听企业微信 WebSocket 连接
+ * 使用 aibot-node-sdk 简化连接管理
+ */
+export declare function monitorWeComProvider(options: WeComMonitorOptions): Promise<void>;

package/dist/src/onboarding.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 企业微信 onboarding adapter for CLI setup wizard.
+ */
+import { type ChannelOnboardingAdapter } from "openclaw/plugin-sdk";
+export declare const wecomOnboardingAdapter: ChannelOnboardingAdapter;

package/dist/src/reqid-store.d.ts

@@ -0,0 +1,31 @@
+/** Store 配置 */
+interface ReqIdStoreOptions {
+    /** TTL 毫秒数，超时的 reqId 视为过期（默认 24 小时） */
+    ttlMs?: number;
+    /** 内存最大条目数（默认 200） */
+    memoryMaxSize?: number;
+    /** 磁盘最大条目数（默认 500） */
+    fileMaxEntries?: number;
+    /** 磁盘写入防抖时间（毫秒），默认 1000ms */
+    flushDebounceMs?: number;
+}
+export interface PersistentReqIdStore {
+    /** 设置 chatId 对应的 reqId（写入内存 + 防抖写磁盘） */
+    set(chatId: string, reqId: string): void;
+    /** 获取 chatId 对应的 reqId（异步：优先内存，miss 时查磁盘并回填内存） */
+    get(chatId: string): Promise<string | undefined>;
+    /** 同步获取 chatId 对应的 reqId（仅内存） */
+    getSync(chatId: string): string | undefined;
+    /** 删除 chatId 对应的 reqId */
+    delete(chatId: string): void;
+    /** 启动时从磁盘预热内存，返回加载条目数 */
+    warmup(onError?: (error: unknown) => void): Promise<number>;
+    /** 立即将内存数据刷写到磁盘（用于优雅退出） */
+    flush(): Promise<void>;
+    /** 清空内存缓存 */
+    clearMemory(): void;
+    /** 返回内存中的条目数 */
+    memorySize(): number;
+}
+export declare function createPersistentReqIdStore(accountId: string, options?: ReqIdStoreOptions): PersistentReqIdStore;
+export {};

package/dist/src/runtime.d.ts

@@ -0,0 +1,3 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+export declare function setWeComRuntime(r: PluginRuntime): void;
+export declare function getWeComRuntime(): PluginRuntime;

package/dist/src/state-manager.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 企业微信全局状态管理模块
+ *
+ * 负责管理 WSClient 实例、消息状态（带 TTL 清理）、ReqId 存储
+ * 解决全局 Map 的内存泄漏问题
+ */
+import type { WSClient } from "@wecom/aibot-node-sdk";
+import type { MessageState } from "./interface.js";
+/**
+ * 获取指定账户的 WSClient 实例
+ */
+export declare function getWeComWebSocket(accountId: string): WSClient | null;
+/**
+ * 设置指定账户的 WSClient 实例
+ */
+export declare function setWeComWebSocket(accountId: string, client: WSClient): void;
+/**
+ * 删除指定账户的 WSClient 实例
+ */
+export declare function deleteWeComWebSocket(accountId: string): void;
+/**
+ * 启动消息状态定期清理（自动 TTL 清理 + 容量限制）
+ */
+export declare function startMessageStateCleanup(): void;
+/**
+ * 停止消息状态定期清理
+ */
+export declare function stopMessageStateCleanup(): void;
+/**
+ * 设置消息状态
+ */
+export declare function setMessageState(messageId: string, state: MessageState): void;
+/**
+ * 获取消息状态
+ */
+export declare function getMessageState(messageId: string): MessageState | undefined;
+/**
+ * 删除消息状态
+ */
+export declare function deleteMessageState(messageId: string): void;
+/**
+ * 清空所有消息状态
+ */
+export declare function clearAllMessageStates(): void;
+/**
+ * 设置 chatId 对应的 reqId（写入内存 + 防抖写磁盘）
+ */
+export declare function setReqIdForChat(chatId: string, reqId: string, accountId?: string): void;
+/**
+ * 获取 chatId 对应的 reqId（异步：优先内存，miss 时查磁盘并回填内存）
+ */
+export declare function getReqIdForChatAsync(chatId: string, accountId?: string): Promise<string | undefined>;
+/**
+ * 获取 chatId 对应的 reqId（同步：仅内存，保留向后兼容）
+ */
+export declare function getReqIdForChat(chatId: string, accountId?: string): string | undefined;
+/**
+ * 删除 chatId 对应的 reqId
+ */
+export declare function deleteReqIdForChat(chatId: string, accountId?: string): void;
+/**
+ * 启动时预热 reqId 缓存（从磁盘加载到内存）
+ */
+export declare function warmupReqIdStore(accountId?: string, log?: (...args: unknown[]) => void): Promise<number>;
+/**
+ * 立即将 reqId 数据刷写到磁盘（用于优雅退出）
+ */
+export declare function flushReqIdStore(accountId?: string): Promise<void>;
+/**
+ * 清理指定账户的所有资源
+ */
+export declare function cleanupAccount(accountId: string): Promise<void>;
+/**
+ * 清理所有资源（用于进程退出）
+ */
+export declare function cleanupAll(): Promise<void>;

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/utils.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 企业微信公共工具函数
+ */
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+/**
+ * 企业微信配置类型
+ */
+/**
+ * 企业微信群组配置
+ */
+export interface WeComGroupConfig {
+    /** 群组内发送者白名单（仅列表中的成员消息会被处理） */
+    allowFrom?: Array<string | number>;
+}
+/**
+ * 企业微信配置类型
+ */
+export interface WeComConfig {
+    enabled?: boolean;
+    websocketUrl?: string;
+    botId?: string;
+    secret?: string;
+    name?: string;
+    allowFrom?: Array<string | number>;
+    dmPolicy?: "open" | "allowlist" | "pairing" | "disabled";
+    /** 群组访问策略："open" = 允许所有群组（默认），"allowlist" = 仅允许 groupAllowFrom 中的群组，"disabled" = 禁用群组消息 */
+    groupPolicy?: "open" | "allowlist" | "disabled";
+    /** 群组白名单（仅 groupPolicy="allowlist" 时生效） */
+    groupAllowFrom?: Array<string | number>;
+    /** 每个群组的详细配置（如群组内发送者白名单） */
+    groups?: Record<string, WeComGroupConfig>;
+    /** 是否发送"思考中"消息，默认为 true */
+    sendThinkingMessage?: boolean;
+}
+export declare const DefaultWsUrl = "wss://openws.work.weixin.qq.com";
+export interface ResolvedWeComAccount {
+    accountId: string;
+    name: string;
+    enabled: boolean;
+    websocketUrl: string;
+    botId: string;
+    secret: string;
+    /** 是否发送"思考中"消息，默认为 true */
+    sendThinkingMessage: boolean;
+    config: WeComConfig;
+}
+/**
+ * 解析企业微信账户配置
+ */
+export declare function resolveWeComAccount(cfg: OpenClawConfig): ResolvedWeComAccount;
+/**
+ * 设置企业微信账户配置
+ */
+export declare function setWeComAccount(cfg: OpenClawConfig, account: Partial<WeComConfig>): OpenClawConfig;
+/**
+ * 生成企业微信请求 ID
+ * @param prefix - 请求类型前缀（subscribe, ping, response 等）
+ * @returns 格式化的请求 ID
+ */
+export declare function generateReqId(prefix: string): string;
+/**
+ * 判断 req_id 的类型
+ * @param reqId - 请求 ID
+ * @returns 请求类型（subscribe, ping, response 等）
+ */
+export declare function getReqIdType(reqId: string): string | null;
+/**
+ * 检查 req_id 是否为指定类型
+ * @param reqId - 请求 ID
+ * @param type - 请求类型
+ * @returns 是否匹配
+ */
+export declare function isReqIdType(reqId: string, type: string): boolean;

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "wecom",
+  "channels": [
+    "wecom"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@wecom/wecom-openclaw-plugin",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "rollup -c -w",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "publish:release": "npm run prebuild && npm run build && npm publish"
+  },
+  "description": "OpenClaw WeCom (企业微信) channel plugin",
+  "openclaw": {
+    "extensions": [
+      "./dist/index.esm.js"
+    ],
+    "channel": {
+      "id": "wecom",
+      "label": "企业微信",
+      "selectionLabel": "企业微信 (WeCom)",
+      "docsPath": "/channels/wecom",
+      "docsLabel": "wecom-openclaw-plugin",
+      "blurb": "企业微信机器人接入插件",
+      "order": 80,
+      "quickstartAllowFrom": true
+    },
+    "install": {
+      "npmSpec": "@wecom/wecom-openclaw-plugin",
+      "localPath": "extensions/wecom-openclaw-plugin",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "@wecom/aibot-node-sdk": "^1.0.0",
+    "file-type": "^21.3.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "openclaw": ">=2026.1.29",
+    "rollup": "^4.9.6",
+    "rollup-plugin-dts": "^6.1.0",
+    "tslib": "^2.6.2",
+    "typescript": "^5.3.3"
+  }
+}