@yanhaidao/wecom 2.3.10 → 2.3.13

package/src/transport/bot-ws/reply.ts

@@ -1,29 +1,93 @@
+import { formatErrorMessage } from "openclaw/plugin-sdk";
 import { generateReqId, type WsFrame, type BaseMessage, type EventMessage, type WSClient } from "@wecom/aibot-node-sdk";
 
 import type { ReplyHandle, ReplyPayload } from "../../types/index.js";
 
+const PLACEHOLDER_KEEPALIVE_MS = 3000;
+
+function isInvalidReqIdError(error: unknown): boolean {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const errcode = "errcode" in error ? Number(error.errcode) : undefined;
+  const errmsg = "errmsg" in error ? String(error.errmsg ?? "") : "";
+  return errcode === 846605 || errmsg.includes("invalid req_id");
+}
+
+function isExpiredStreamUpdateError(error: unknown): boolean {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const errcode = "errcode" in error ? Number(error.errcode) : undefined;
+  const errmsg = "errmsg" in error ? String(error.errmsg ?? "").toLowerCase() : "";
+  return errcode === 846608 || errmsg.includes("stream message update expired");
+}
+
+/** SDK rejects with a plain Error whose message contains "ack timeout" when
+ * the WeCom server does not acknowledge a reply within 5 s.  Once timed out
+ * the reqId slot is released; further replies on the same reqId will fail. */
+function isAckTimeoutError(error: unknown): boolean {
+  return error instanceof Error && error.message.includes("ack timeout");
+}
+
+function isTerminalReplyError(error: unknown): boolean {
+  return isInvalidReqIdError(error) || isExpiredStreamUpdateError(error) || isAckTimeoutError(error);
+}
+
 export function createBotWsReplyHandle(params: {
   client: WSClient;
   frame: WsFrame<BaseMessage | EventMessage>;
   accountId: string;
+  placeholderContent?: string;
+  autoSendPlaceholder?: boolean;
   onDeliver?: () => void;
   onFail?: (error: unknown) => void;
 }): ReplyHandle {
   let streamId: string | undefined;
+  let accumulatedText = "";
   const resolveStreamId = () => {
     streamId ||= generateReqId("stream");
     return streamId;
   };
 
-  let ackSent = false;
-  const ackTimer = setTimeout(() => {
-    if (ackSent) return;
-    ackSent = true;
-    params.client.replyStream(params.frame, resolveStreamId(), "⏳ 正在思考中...\n\n", false)
-      .catch(() => { /* ignore */ });
-  }, 4000);
+  const placeholderText = params.placeholderContent?.trim() || "⏳ 正在思考中...\n\n";
+  let streamSettled = false;
+  let placeholderInFlight = false;
+  let placeholderKeepalive: ReturnType<typeof setInterval> | undefined;
 
-  const cleanupTimer = () => clearTimeout(ackTimer);
+  const stopPlaceholderKeepalive = () => {
+    if (!placeholderKeepalive) return;
+    clearInterval(placeholderKeepalive);
+    placeholderKeepalive = undefined;
+  };
+
+  const settleStream = () => {
+    streamSettled = true;
+    stopPlaceholderKeepalive();
+  };
+
+  const sendPlaceholder = () => {
+    if (streamSettled || placeholderInFlight) return;
+    placeholderInFlight = true;
+    params.client.replyStream(params.frame, resolveStreamId(), placeholderText, false)
+      .catch((error) => {
+        if (!isTerminalReplyError(error)) {
+          return;
+        }
+        settleStream();
+        params.onFail?.(error);
+      })
+      .finally(() => {
+        placeholderInFlight = false;
+      });
+  };
+
+  if (params.autoSendPlaceholder !== false) {
+    sendPlaceholder();
+    placeholderKeepalive = setInterval(() => {
+      sendPlaceholder();
+    }, PLACEHOLDER_KEEPALIVE_MS);
+  }
 
   return {
     context: {
@@ -40,23 +104,53 @@ export function createBotWsReplyHandle(params: {
     },
     deliver: async (payload: ReplyPayload, info) => {
       if (payload.isReasoning) return;
-      
+
       const text = payload.text?.trim();
       if (!text) return;
 
-      if (!ackSent) {
-        cleanupTimer();
-        ackSent = true;
+      if (info.kind === "block") {
+        accumulatedText = accumulatedText ? `${accumulatedText}\n${text}` : text;
+      }
+
+      const outboundText =
+        info.kind === "final"
+          ? accumulatedText
+            ? text
+              ? `${accumulatedText}\n${text}`
+              : accumulatedText
+            : text
+          : accumulatedText || text;
+
+      settleStream();
+      try {
+        await params.client.replyStream(
+          params.frame,
+          resolveStreamId(),
+          outboundText,
+          info.kind === "final",
+        );
+      } catch (error) {
+        if (isTerminalReplyError(error)) {
+          params.onFail?.(error);
+          return;
+        }
+        throw error;
       }
-      
-      await params.client.replyStream(params.frame, resolveStreamId(), text, info.kind === "final");
       params.onDeliver?.();
     },
     fail: async (error: unknown) => {
-      cleanupTimer();
-      ackSent = true;
-      const message = error instanceof Error ? error.message : String(error);
-      await params.client.replyStream(params.frame, resolveStreamId(), `WeCom WS reply failed: ${message}`, true);
+      settleStream();
+      if (isTerminalReplyError(error)) {
+        params.onFail?.(error);
+        return;
+      }
+      const message = formatErrorMessage(error);
+      try {
+        await params.client.replyStream(params.frame, resolveStreamId(), `WeCom WS reply failed: ${message}`, true);
+      } catch (sendError) {
+        params.onFail?.(sendError);
+        return;
+      }
       params.onFail?.(error);
     },
   };

package/src/transport/bot-ws/sdk-adapter.test.ts

@@ -0,0 +1,124 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const sdkMockState = vi.hoisted(() => {
+  class MockWSClient {
+    readonly handlers = new Map<string, Array<(payload: any) => void>>();
+    readonly isConnected = true;
+    readonly replyStream = vi.fn().mockResolvedValue(undefined);
+
+    constructor(_options: unknown) {
+      sdkMockState.client = this;
+    }
+
+    on(event: string, handler: (payload: any) => void): void {
+      const current = this.handlers.get(event) ?? [];
+      current.push(handler);
+      this.handlers.set(event, current);
+    }
+
+    emit(event: string, payload: any): void {
+      for (const handler of this.handlers.get(event) ?? []) {
+        handler(payload);
+      }
+    }
+
+    connect(): void {}
+
+    disconnect(): void {}
+  }
+
+  return {
+    client: null as InstanceType<typeof MockWSClient> | null,
+    MockWSClient,
+  };
+});
+
+vi.mock("@wecom/aibot-node-sdk", () => ({
+  default: {
+    WSClient: sdkMockState.MockWSClient,
+  },
+  WSClient: sdkMockState.MockWSClient,
+  generateReqId: (prefix: string) => `${prefix}-1`,
+}));
+
+import { BotWsSdkAdapter } from "./sdk-adapter.js";
+
+const waitForAsyncCallbacks = async () => {
+  await Promise.resolve();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+};
+
+describe("BotWsSdkAdapter", () => {
+  const unhandledRejections: unknown[] = [];
+  const onUnhandledRejection = (reason: unknown) => {
+    unhandledRejections.push(reason);
+  };
+
+  afterEach(() => {
+    process.off("unhandledRejection", onUnhandledRejection);
+    unhandledRejections.length = 0;
+    sdkMockState.client = null;
+  });
+
+  it("contains frame handler rejections instead of leaking unhandled rejections", async () => {
+    process.on("unhandledRejection", onUnhandledRejection);
+
+    const runtime = {
+      account: {
+        accountId: "acc-1",
+        bot: {
+          wsConfigured: true,
+          ws: {
+            botId: "bot-1",
+            secret: "secret-1",
+          },
+          config: {},
+        },
+      },
+      handleEvent: vi.fn().mockRejectedValue(new Error("frame exploded")),
+      updateTransportSession: vi.fn(),
+      touchTransportSession: vi.fn(),
+      recordOperationalIssue: vi.fn(),
+    };
+    const log = {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    };
+
+    new BotWsSdkAdapter(runtime as any, log as any).start();
+
+    sdkMockState.client?.emit("message", {
+      cmd: "aibot_msg_callback",
+      headers: { req_id: "req-1" },
+      body: {
+        msgid: "msg-1",
+        msgtype: "text",
+        from: { userid: "user-1" },
+        text: { content: "hello" },
+      },
+    });
+
+    await waitForAsyncCallbacks();
+
+    expect(runtime.handleEvent).toHaveBeenCalledTimes(1);
+    expect(runtime.recordOperationalIssue).toHaveBeenCalledWith(
+      expect.objectContaining({
+        transport: "bot-ws",
+        category: "runtime-error",
+        messageId: "msg-1",
+        error: "frame exploded",
+      }),
+    );
+    expect(runtime.touchTransportSession).toHaveBeenCalledWith(
+      "bot-ws",
+      expect.objectContaining({
+        lastError: "frame exploded",
+      }),
+    );
+    expect(log.error).toHaveBeenCalledWith(
+      expect.stringContaining("frame handler failed account=acc-1 reqId=req-1 message=frame exploded"),
+    );
+    expect(unhandledRejections).toHaveLength(0);
+  });
+});

package/src/transport/bot-ws/sdk-adapter.ts

@@ -3,6 +3,7 @@ import crypto from "node:crypto";
 import AiBot, { type BaseMessage, type EventMessage, type WsFrame } from "@wecom/aibot-node-sdk";
 
 import type { RuntimeLogSink } from "../../types/index.js";
+import { registerBotWsPushHandle, unregisterBotWsPushHandle } from "../../app/index.js";
 import { mapBotWsFrameToInboundEvent } from "./inbound.js";
 import { createBotWsReplyHandle } from "./reply.js";
 import { createBotWsSessionSnapshot } from "./session.js";
@@ -38,6 +39,23 @@ export class BotWsSdkAdapter {
       },
     });
     this.client = client;
+    registerBotWsPushHandle(this.runtime.account.accountId, {
+      isConnected: () => client.isConnected,
+      sendMarkdown: async (chatId, content) => {
+        await client.sendMessage(chatId, {
+          msgtype: "markdown",
+          markdown: { content },
+        });
+        this.runtime.touchTransportSession("bot-ws", {
+          ownerId: this.ownerId,
+          running: true,
+          connected: client.isConnected,
+          authenticated: client.isConnected,
+          lastOutboundAt: Date.now(),
+          lastError: undefined,
+        });
+      },
+    });
 
     client.on("connected", () => {
       this.log.info?.(`[wecom-ws] connected account=${this.runtime.account.accountId}`);
@@ -131,6 +149,13 @@ export class BotWsSdkAdapter {
         client,
         frame,
         accountId: this.runtime.account.accountId,
+        placeholderContent: botAccount.config.streamPlaceholderContent,
+        autoSendPlaceholder:
+          event.inboundKind === "text" ||
+          event.inboundKind === "image" ||
+          event.inboundKind === "file" ||
+          event.inboundKind === "voice" ||
+          event.inboundKind === "mixed",
         onDeliver: () => {
           this.runtime.touchTransportSession("bot-ws", {
             ownerId: this.ownerId,
@@ -153,11 +178,41 @@ export class BotWsSdkAdapter {
       await this.runtime.handleEvent(event, replyHandle);
     };
 
+    const runHandleFrame = (frame: WsFrame<BaseMessage | EventMessage>) => {
+      void handleFrame(frame).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        this.log.error?.(
+          `[wecom-ws] frame handler failed account=${this.runtime.account.accountId} reqId=${frame.headers?.req_id ?? "n/a"} message=${message}`,
+        );
+        this.runtime.recordOperationalIssue({
+          transport: "bot-ws",
+          category: "runtime-error",
+          messageId: frame.body?.msgid,
+          raw: {
+            transport: "bot-ws",
+            command: frame.cmd,
+            headers: frame.headers,
+            body: frame.body,
+            envelopeType: "ws",
+          },
+          summary: `bot-ws frame handler crashed reqId=${frame.headers?.req_id ?? "n/a"}`,
+          error: message,
+        });
+        this.runtime.touchTransportSession("bot-ws", {
+          ownerId: this.ownerId,
+          running: client.isConnected,
+          connected: client.isConnected,
+          authenticated: client.isConnected,
+          lastError: message,
+        });
+      });
+    };
+
     client.on("message", (frame) => {
-      void handleFrame(frame);
+      runHandleFrame(frame);
     });
     client.on("event", (frame) => {
-      void handleFrame(frame);
+      runHandleFrame(frame);
     });
 
     client.connect();
@@ -165,6 +220,7 @@ export class BotWsSdkAdapter {
 
   stop(): void {
     this.log.info?.(`[wecom-ws] stop account=${this.runtime.account.accountId}`);
+    unregisterBotWsPushHandle(this.runtime.account.accountId);
     this.runtime.updateTransportSession(
       createBotWsSessionSnapshot({
         accountId: this.runtime.account.accountId,

package/CLAUDE.md

@@ -1,238 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-This is an **OpenClaw Channel Plugin** for WeCom (企业微信 / WeChat Work). It enables AI bot integration with enterprise WeChat through a dual-mode architecture.
-
-- **Package**: `@yanhaidao/wecom`
-- **Type**: ES Module (NodeNext)
-- **Entry**: `index.ts`
-
-## Architecture
-
-### Dual-Mode Design (Bot + Agent)
-
-The plugin implements a unique dual-mode architecture:
-
-| Mode | Purpose | Webhook Path | Capabilities |
-|------|---------|--------------|--------------|
-| **Bot** (智能体) | Real-time streaming chat | `/wecom`, `/wecom/bot` | Streaming responses, low latency, text/image only |
-| **Agent** (自建应用) | Fallback & broadcast | `/wecom/agent` | File sending, broadcasts, long tasks (>6min) |
-
-**Key Design Principle**: Bot is preferred for conversations; Agent is used as fallback when Bot cannot deliver (files, timeouts) or for proactive broadcasts.
-
-### Core Components
-
-```
-index.ts              # Plugin entry - registers channel and HTTP handlers
-src/
-  channel.ts          # ChannelPlugin implementation, lifecycle management
-  monitor.ts          # Core webhook handler, message flow, stream state
-  runtime.ts          # Runtime state singleton
-  http.ts             # HTTP client with undici + proxy support
-  crypto.ts           # AES-CBC encryption/decryption for webhooks
-  media.ts            # Media file download/decryption
-  outbound.ts         # Outbound message adapter
-  target.ts           # Target resolution (user/party/tag/chat)
-  dynamic-agent.ts    # Dynamic agent routing (per-user/per-group isolation)
-  agent/
-    api-client.ts     # WeCom API client with AccessToken caching
-    handler.ts        # XML webhook handler for Agent mode
-  config/
-    schema.ts         # Zod schemas for configuration
-  monitor/
-    state.ts          # StreamStore and ActiveReplyStore with TTL pruning
-  types/constants.ts  # API endpoints and limits
-```
-
-### Stream State Management
-
-The plugin uses a sophisticated stream state system (`src/monitor/state.ts`):
-
-- **StreamStore**: Manages message streams with 6-minute timeout window
-- **ActiveReplyStore**: Tracks `response_url` for proactive pushes
-- **Pending Queue**: Debounces rapid messages (500ms default)
-- **Message Deduplication**: Uses `msgid` to prevent duplicate processing
-
-### Token Management
-
-Agent mode uses automatic AccessToken caching (`src/agent/api-client.ts`):
-- Token cached with 60-second refresh buffer
-- Automatic retry on expiration
-- Thread-safe refresh deduplication
-
-## Development Commands
-
-### Testing
-
-This project uses **Vitest**. Tests extend from a base config at `../../vitest.config.ts`:
-
-```bash
-# Run all tests
-npx vitest --config vitest.config.ts
-
-# Run specific test file
-npx vitest --config vitest.config.ts src/crypto.test.ts
-
-# Run tests matching pattern
-npx vitest --config vitest.config.ts --testNamePattern="should encrypt"
-
-# Watch mode
-npx vitest --config vitest.config.ts --watch
-```
-
-Test files are located alongside source files with `.test.ts` suffix:
-- `src/crypto.test.ts`
-- `src/monitor.integration.test.ts`
-- `src/monitor/state.queue.test.ts`
-- etc.
-
-### Type Checking
-
-```bash
-npx tsc --noEmit
-```
-
-### Build
-
-The plugin is loaded directly as TypeScript by OpenClaw. No build step is required for development, but type checking is recommended.
-
-## Configuration Schema
-
-Configuration is validated via Zod (`src/config/schema.ts`):
-
-```typescript
-{
-  enabled: boolean,
-  bot: {
-    token: string,              // Bot webhook token
-    encodingAESKey: string,     // AES encryption key
-    receiveId: string?,         // Optional receive ID
-    streamPlaceholderContent: string?,  // "Thinking..."
-    welcomeText: string?,
-    dm: { policy, allowFrom }
-  },
-  agent: {
-    corpId: string,
-    corpSecret: string,
-    agentId: number,
-    token: string,              // Callback token
-    encodingAESKey: string,     // Callback AES key
-    welcomeText: string?,
-    dm: { policy, allowFrom }
-  },
-  network: {
-    egressProxyUrl: string?     // For dynamic IP scenarios
-  },
-  media: {
-    maxBytes: number?           // Default 25MB
-  },
-  dynamicAgents: {
-    enabled: boolean?           // Enable per-user/per-group agents
-    dmCreateAgent: boolean?     // Create agent per DM user
-    groupEnabled: boolean?      // Enable for group chats
-    adminUsers: string[]?       // Admin users (bypass dynamic routing)
-  }
-}
-```
-
-### Dynamic Agent Routing
-
-When `dynamicAgents.enabled` is `true`, the plugin automatically creates isolated Agent instances for each user/group:
-
-```bash
-# Enable dynamic agents
-openclaw config set channels.wecom.dynamicAgents.enabled true
-
-# Configure admin users (use main agent)
-openclaw config set channels.wecom.dynamicAgents.adminUsers '["admin1","admin2"]'
-```
-
-**Generated Agent ID format**: `wecom-{type}-{peerId}`
-- DM: `wecom-dm-zhangsan`
-- Group: `wecom-group-wr123456`
-
-Dynamic agents are automatically added to `agents.list` in the config file.
-
-## Key Technical Details
-
-### Webhook Security
-
-- **Signature Verification**: HMAC-SHA256 with token
-- **Encryption**: AES-CBC with PKCS#7 padding (32-byte blocks)
-- **Paths**: `/wecom` (legacy), `/wecom/bot`, `/wecom/agent`
-
-### Timeout Handling
-
-Bot mode has a 6-minute window (360s) for streaming responses. The plugin:
-- Tracks deadline: `createdAt + 6 * 60 * 1000`
-- Switches to Agent fallback at `deadline - 30s` margin
-- Sends DM via Agent for remaining content
-
-### Media Handling
-
-- **Inbound**: Decrypts WeCom encrypted media URLs
-- **Outbound Images**: Base64 encoded via `msg_item` in stream
-- **Outbound Files**: Requires Agent mode, sent via `media/upload` + `message/send`
-- **Max Size**: 25MB default (configurable via `channels.wecom.media.maxBytes`)
-
-### Proxy Support
-
-For servers with dynamic IPs (common error: `60020 not allow to access from your ip`):
-
-```bash
-openclaw config set channels.wecom.network.egressProxyUrl "http://proxy.company.local:3128"
-```
-
-## Testing Notes
-
-- Tests use Vitest with `../../vitest.config.ts` as base
-- Integration tests mock WeCom API responses
-- Crypto tests verify AES encryption round-trips
-- Monitor tests cover stream state transitions and queue behavior
-
-## Common Patterns
-
-### Adding a New Message Type Handler
-
-1. Update `buildInboundBody()` in `src/monitor.ts` to parse the message
-2. Add type definitions in `src/types/message.ts`
-3. Update `processInboundMessage()` if media handling is needed
-
-### Agent API Calls
-
-Always use `api-client.ts` methods which handle token management:
-
-```typescript
-import { sendText, uploadMedia } from "./agent/api-client.js";
-
-// Token is automatically cached and refreshed
-await sendText({ agent, toUser: "userid", text: "Hello" });
-```
-
-### Stream Content Updates
-
-Use `streamStore.updateStream()` for thread-safe updates:
-
-```typescript
-streamStore.updateStream(streamId, (state) => {
-  state.content = "new content";
-  state.finished = true;
-});
-```
-
-## Dependencies
-
-- `undici`: HTTP client with proxy support
-- `fast-xml-parser`: XML parsing for Agent callbacks
-- `zod`: Configuration validation
-- `openclaw`: Peer dependency (>=2026.2.24)
-
-## WeCom API Endpoints Used
-
-- `GET_TOKEN`: `https://qyapi.weixin.qq.com/cgi-bin/gettoken`
-- `SEND_MESSAGE`: `https://qyapi.weixin.qq.com/cgi-bin/message/send`
-- `UPLOAD_MEDIA`: `https://qyapi.weixin.qq.com/cgi-bin/media/upload`
-- `DOWNLOAD_MEDIA`: `https://qyapi.weixin.qq.com/cgi-bin/media/get`