@wecom/wecom-openclaw-plugin 2026.3.20-beta.6 → 2026.3.20

package/README.md

@@ -1,3 +1,11 @@
+> 💡 **快速上手指引 & 交流群**
+>
+> 📖 [点击查看完整接入指引文档](https://doc.weixin.qq.com/doc/w3_AFYA1wY6ACoCNRxfnyGRJQaSa6jjJ?scode=AJEAIQdfAAo0RJmzxLAFYA1wY6ACo) — 包含配置步骤、产品介绍、常见问题解答等。
+>
+> 💬 扫码加入企业微信交流群：
+>
+> <img src="https://wwcdn.weixin.qq.com/node/wework/images/202603181801.a77d987fb8.png" alt="扫码入群交流" width="200" />
+
 # 🤖 WeCom OpenClaw Plugin
 
 **WeCom channel plugin for [OpenClaw](https://github.com/openclaw)** — by the Tencent WeCom team.

package/dist/index.cjs.js

@@ -386,8 +386,10 @@ const REPLY_SEND_TIMEOUT_MS = 15000;
 const MESSAGE_PROCESS_TIMEOUT_MS = 5 * 60 * 1000;
 /** WebSocket 心跳间隔（毫秒） */
 const WS_HEARTBEAT_INTERVAL_MS = 30000;
-/** WebSocket 最大重连次数 */
-const WS_MAX_RECONNECT_ATTEMPTS = 100;
+/** WebSocket 连接断开时的最大重连次数 */
+const WS_MAX_RECONNECT_ATTEMPTS = 10;
+/** WebSocket 认证失败时的最大重试次数 */
+const WS_MAX_AUTH_FAILURE_ATTEMPTS = 5;
 // ============================================================================
 // 消息状态管理配置
 // ============================================================================
@@ -2095,8 +2097,8 @@ function createSdkLogger(runtime, accountId) {
  * 使用 aibot-node-sdk 简化连接管理
  */
 async function monitorWeComProvider(options) {
-    const { account, config, runtime, abortSignal } = options;
-    runtime.log?.(`[${account.accountId}] Initializing WSClient with SDK...`);
+    const { account, config, runtime, abortSignal, setStatus } = options;
+    runtime.log?.(`[${account.accountId}] [${PLUGIN_VERSION}] Initializing WSClient with SDK...`);
     // 启动消息状态定期清理
     startMessageStateCleanup();
     return new Promise((resolve, reject) => {
@@ -2108,18 +2110,26 @@ async function monitorWeComProvider(options) {
             logger,
             heartbeatInterval: WS_HEARTBEAT_INTERVAL_MS,
             maxReconnectAttempts: WS_MAX_RECONNECT_ATTEMPTS,
+            maxAuthFailureAttempts: WS_MAX_AUTH_FAILURE_ATTEMPTS,
             scene: SCENE_WECOM_OPENCLAW,
             plug_version: PLUGIN_VERSION,
         });
-        // 清理函数：确保所有资源被释放
+        // 防止 cleanup 被多次调用（abort handler、error handler、disconnected_event 可能竞态触发）
+        let cleanedUp = false;
+        // 清理函数：确保所有资源被释放（幂等）
         const cleanup = async () => {
+            if (cleanedUp)
+                return;
+            cleanedUp = true;
             stopMessageStateCleanup();
             await cleanupAccount(account.accountId);
         };
-        // 处理中止信号
+        // 处理中止信号（框架 stopChannel 会触发 abort）
+        // resolve() 让 Promise settle → 框架清理 store.tasks/store.aborts
         if (abortSignal) {
             abortSignal.addEventListener("abort", async () => {
                 runtime.log?.(`[${account.accountId}] Connection aborted`);
+                wsClient.disconnect();
                 await cleanup();
                 resolve();
             });
@@ -2137,16 +2147,84 @@ async function monitorWeComProvider(options) {
         wsClient.on("disconnected", (reason) => {
             runtime.log?.(`[${account.accountId}] WebSocket disconnected: ${reason}`);
         });
+        // 监听被踢下线事件（服务端因新连接建立而主动断开旧连接）
+        //
+        // SDK 内部已设置 isManualClose=true 阻止 SDK 层自动重连，连接不会自行恢复。
+        // **不 reject/resolve Promise**——保持 pending 以阻止框架层 auto-restart。
+        //
+        // 为什么不能 reject/resolve：
+        //   - reject → 框架 auto-restart 介入 → 新连接建立 → 又被踢 → 两个实例互踢无限循环
+        //   - resolve → 同上，框架 .then() 中的 auto-restart 也会触发
+        //
+        // Promise pending 的安全性：
+        //   - store.tasks.has(id) = true → 阻止 Health Monitor 直接 startChannel（startChannel 检查 tasks.has）
+        //   - 框架 stopChannel → abort() → abort handler 中 resolve() → tasks 正常清理
+        //   - 用户修改配置 → config reload → stopChannel + startChannel → 正常恢复
+        //
+        // 显式调用 wsClient.disconnect() 确保 SDK 内部资源（定时器、队列等）完全释放。
+        wsClient.on("event.disconnected_event", async () => {
+            const errorMsg = `Kicked by server: a new connection was established elsewhere. Auto-restart is suppressed to avoid mutual kicking. Please check for duplicate instances.`;
+            runtime.error?.(`[${account.accountId}] ${errorMsg}`);
+            wsClient.disconnect();
+            await cleanup();
+            setStatus?.({
+                accountId: account.accountId,
+                running: false,
+                lastError: errorMsg,
+                lastStopAt: Date.now(),
+            });
+            // Promise 保持 pending，不触发 auto-restart
+        });
         // 监听重连事件
         wsClient.on("reconnecting", (attempt) => {
             runtime.log?.(`[${account.accountId}] Reconnecting attempt ${attempt}...`);
         });
         // 监听错误事件
-        wsClient.on("error", (error) => {
+        wsClient.on("error", async (error) => {
             runtime.error?.(`[${account.accountId}] WebSocket error: ${error.message}`);
-            // 认证失败时拒绝 Promise
-            if (error.message.includes("Authentication failed")) {
+            if (error instanceof aibotNodeSdk.WSAuthFailureError) {
+                // 认证失败重试次数用尽（SDK 层已重试 WS_MAX_AUTH_FAILURE_ATTEMPTS 次）。
+                // 配置错误（如 botId/secret 无效），框架 auto-restart 也无法恢复。
+                //
+                // **不 reject/resolve Promise**——保持 pending 以阻止框架层 auto-restart。
+                //
+                // 为什么不能 reject/resolve：
+                //   - reject/resolve → 框架 auto-restart（最多 10 次）× SDK 重试（5 次）= 60 次无意义尝试
+                //   - 且 Health Monitor 每小时还会 resetRestartAttempts 再来一轮
+                //
+                // Promise pending 的安全性：同被踢下线场景
+                //   - store.tasks.has(id) = true → 阻止 Health Monitor 直接 startChannel
+                //   - 框架 stopChannel / config reload → abort handler 中 resolve() → 正常清理
+                //   - 用户修改配置后框架通过 reload 机制重新启动
+                const errorMsg = `Auth failure attempts exhausted (${WS_MAX_AUTH_FAILURE_ATTEMPTS} attempts). Please check botId/secret configuration.`;
+                runtime.error?.(`[${account.accountId}] ${errorMsg}`);
+                wsClient.disconnect();
+                await cleanup();
+                setStatus?.({
+                    accountId: account.accountId,
+                    running: false,
+                    lastError: errorMsg,
+                    lastStopAt: Date.now(),
+                });
+                return;
+            }
+            if (error instanceof aibotNodeSdk.WSReconnectExhaustedError) {
+                // 网络断线重连次数用尽（SDK 层已重试 WS_MAX_RECONNECT_ATTEMPTS 次）。
+                // 通常是网络/服务端问题，框架 auto-restart 可能恢复。
+                //
+                // reject Promise → 框架 auto-restart 介入（最多 MAX_RESTART_ATTEMPTS=10 次）
+                // 总连接尝试次数 = (1 首次 + WS_MAX_RECONNECT_ATTEMPTS 重连) × (1 首轮 + 10 auto-restart)
+                //                = 11 × 11 = 121 次
+                //
+                // 如果 Health Monitor 介入（每 5 分钟检查），会 resetRestartAttempts 重新计数，
+                // 受限于 DEFAULT_MAX_RESTARTS_PER_HOUR=10，每小时最多额外 10 × 121 = 1210 次。
+                // 但因网络断线通常是暂时性的，auto-restart + Health Monitor 的兜底机制是合理的。
+                //
+                // 显式调用 wsClient.disconnect() 确保 SDK 内部资源完全释放，
+                // 避免旧实例的定时器/队列残留。
+                wsClient.disconnect();
                 cleanup().finally(() => reject(error));
+                return;
             }
         });
         // 监听版本检查事件：收到 enter_check_update 时回复当前插件版本
@@ -2639,6 +2717,7 @@ const wecomPlugin = {
                 config: ctx.cfg,
                 runtime: ctx.runtime,
                 abortSignal: ctx.abortSignal,
+                setStatus: ctx.setStatus,
             });
         },
         logoutAccount: async ({ cfg }) => {
@@ -3319,8 +3398,12 @@ async function interceptMediaResponse(result) {
     // 5. 检测 contentType，并通过 saveMediaBuffer 保存到本地媒体目录
     const contentType = await detectMime({ buffer, filePath: mediaName }) ?? "application/octet-stream";
     const tMimeDetected = performance.now();
+    // 企业微信聊天记录附件可达 20MB（文件消息上限），
+    // 而 saveMediaBuffer 默认 maxBytes 为 5MB（针对 outbound 场景），
+    // 此处显式放宽到 20MB 以支持大文件下载。
+    const INBOUND_MAX_BYTES = 20 * 1024 * 1024; // 20MB
     const core = getWeComRuntime();
-    const saved = await core.channel.media.saveMediaBuffer(buffer, contentType, "inbound", undefined, // maxBytes: 使用 saveMediaBuffer 内部默认值
+    const saved = await core.channel.media.saveMediaBuffer(buffer, contentType, "inbound", INBOUND_MAX_BYTES, // maxBytes: 放宽到 20MB，匹配企业微信文件消息上限
     mediaName);
     // 5.1 补偿：核心库 EXT_BY_MIME 可能缺少某些格式映射（如 audio/amr），
     //     导致保存的文件没有后缀。此处检测并修复。
@@ -3486,7 +3569,6 @@ function createWeComMcpTool() {
     };
 }
 
-console.log(`[wecom] v${PLUGIN_VERSION} loaded`);
 const plugin = {
     id: "wecom-openclaw-plugin",
     name: "企业微信",