@yanhaidao/wecom 2.3.9 → 2.3.12

package/src/outbound.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
 vi.mock("./transport/agent-api/core.js", () => ({
   sendText: vi.fn(),
@@ -7,6 +7,13 @@ vi.mock("./transport/agent-api/core.js", () => ({
 }));
 
 describe("wecomOutbound", () => {
+  afterEach(async () => {
+    const runtime = await import("./runtime.js");
+    runtime.unregisterBotWsPushHandle("default");
+    runtime.unregisterBotWsPushHandle("acct-ws");
+    vi.unstubAllGlobals();
+  });
+
   it("does not crash when called with core outbound params", async () => {
     const { wecomOutbound } = await import("./outbound.js");
     await expect(
@@ -16,7 +23,7 @@ describe("wecomOutbound", () => {
         text: "caption",
         mediaUrl: "https://example.com/media.png",
       } as any),
-    ).rejects.toThrow(/account "default" not found/i);
+    ).rejects.toThrow(/requires Agent mode for account=default/i);
   });
 
   it("throws explicit error when outbound accountId does not exist", async () => {
@@ -173,6 +180,151 @@ describe("wecomOutbound", () => {
     now.mockRestore();
   });
 
+  it("prefers Bot WS active push for text when ws is the active bot transport", async () => {
+    const { wecomOutbound } = await import("./outbound.js");
+    const runtime = await import("./runtime.js");
+    const api = await import("./transport/agent-api/core.js");
+    const sendMarkdown = vi.fn().mockResolvedValue(undefined);
+    const now = vi.spyOn(Date, "now").mockReturnValue(789);
+    runtime.registerBotWsPushHandle("acct-ws", {
+      isConnected: () => true,
+      sendMarkdown,
+    });
+    (api.sendText as any).mockClear();
+
+    const cfg = {
+      channels: {
+        wecom: {
+          enabled: true,
+          defaultAccount: "acct-ws",
+          accounts: {
+            "acct-ws": {
+              enabled: true,
+              bot: {
+                primaryTransport: "ws",
+                ws: {
+                  botId: "bot-1",
+                  secret: "secret-1",
+                },
+              },
+              agent: {
+                corpId: "corp-ws",
+                corpSecret: "agent-secret",
+                agentId: 10001,
+                token: "token-ws",
+                encodingAESKey: "aes-ws",
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const result = await wecomOutbound.sendText({
+      cfg,
+      accountId: "acct-ws",
+      to: "user:lisi",
+      text: "hello ws",
+    } as any);
+
+    expect(sendMarkdown).toHaveBeenCalledWith("lisi", "hello ws");
+    expect(api.sendText).not.toHaveBeenCalled();
+    expect(result.messageId).toBe("bot-ws-789");
+
+    now.mockRestore();
+  });
+
+  it("does not silently fall back to Agent when Bot WS active push is configured but unavailable", async () => {
+    const { wecomOutbound } = await import("./outbound.js");
+    const api = await import("./transport/agent-api/core.js");
+    (api.sendText as any).mockClear();
+
+    const cfg = {
+      channels: {
+        wecom: {
+          enabled: true,
+          bot: {
+            primaryTransport: "ws",
+            ws: {
+              botId: "bot-1",
+              secret: "secret-1",
+            },
+          },
+          agent: {
+            corpId: "corp",
+            corpSecret: "secret",
+            agentId: 1000002,
+            token: "token",
+            encodingAESKey: "aes",
+          },
+        },
+      },
+    };
+
+    await expect(
+      wecomOutbound.sendText({
+        cfg,
+        to: "user:zhangsan",
+        text: "hello",
+      } as any),
+    ).rejects.toThrow(/no live ws runtime is registered/i);
+    expect(api.sendText).not.toHaveBeenCalled();
+  });
+
+  it("keeps outbound media on Agent even when Bot WS is active", async () => {
+    const { wecomOutbound } = await import("./outbound.js");
+    const runtime = await import("./runtime.js");
+    const api = await import("./transport/agent-api/core.js");
+    const sendMarkdown = vi.fn().mockResolvedValue(undefined);
+    runtime.registerBotWsPushHandle("default", {
+      isConnected: () => true,
+      sendMarkdown,
+    });
+    (api.uploadMedia as any).mockResolvedValue("media-1");
+    (api.sendMedia as any).mockResolvedValue(undefined);
+    (api.sendMedia as any).mockClear();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer,
+        headers: new Headers({ "content-type": "image/png" }),
+      }),
+    );
+
+    const cfg = {
+      channels: {
+        wecom: {
+          enabled: true,
+          bot: {
+            primaryTransport: "ws",
+            ws: {
+              botId: "bot-1",
+              secret: "secret-1",
+            },
+          },
+          agent: {
+            corpId: "corp",
+            corpSecret: "secret",
+            agentId: 1000002,
+            token: "token",
+            encodingAESKey: "aes",
+          },
+        },
+      },
+    };
+
+    await wecomOutbound.sendMedia({
+      cfg,
+      to: "user:zhangsan",
+      text: "caption",
+      mediaUrl: "https://example.com/media.png",
+    } as any);
+
+    expect(api.sendMedia).toHaveBeenCalledTimes(1);
+    expect(sendMarkdown).not.toHaveBeenCalled();
+  });
+
   it("uses account-scoped agent config in matrix mode", async () => {
     const { wecomOutbound } = await import("./outbound.js");
     const api = await import("./transport/agent-api/core.js");

package/src/outbound.ts

@@ -2,9 +2,10 @@ import type { ChannelOutboundAdapter, ChannelOutboundContext } from "openclaw/pl
 
 import { resolveWecomAccount, resolveWecomAccountConflict, resolveWecomAccounts } from "./config/index.js";
 import { WecomAgentDeliveryService } from "./capability/agent/index.js";
-import { getWecomRuntime } from "./runtime.js";
+import { getBotWsPushHandle, getWecomRuntime } from "./runtime.js";
+import { resolveScopedWecomTarget } from "./target.js";
 
-function resolveAgentConfigOrThrow(params: {
+function resolveOutboundAccountOrThrow(params: {
   cfg: ChannelOutboundContext["cfg"];
   accountId?: string | null;
 }) {
@@ -26,10 +27,17 @@ function resolveAgentConfigOrThrow(params: {
       );
     }
   }
-  const account = resolveWecomAccount({
+  return resolveWecomAccount({
     cfg: params.cfg,
     accountId: params.accountId,
-  }).agent;
+  });
+}
+
+function resolveAgentConfigOrThrow(params: {
+  cfg: ChannelOutboundContext["cfg"];
+  accountId?: string | null;
+}) {
+  const account = resolveOutboundAccountOrThrow(params).agent;
   if (!account?.apiConfigured) {
     throw new Error(
       `WeCom outbound requires Agent mode for account=${params.accountId ?? "default"}. Configure channels.wecom.accounts.<accountId>.agent (or legacy channels.wecom.agent).`,
@@ -45,6 +53,81 @@ function resolveAgentConfigOrThrow(params: {
   return account;
 }
 
+function isExplicitAgentTarget(raw: string | undefined): boolean {
+  return /^wecom-agent:/i.test(String(raw ?? "").trim());
+}
+
+function resolveBotWsChatTarget(params: {
+  to: string | undefined;
+  accountId: string;
+}): string | undefined {
+  const scoped = resolveScopedWecomTarget(params.to, params.accountId);
+  if (!scoped) {
+    return undefined;
+  }
+  if (scoped.accountId && scoped.accountId !== params.accountId) {
+    throw new Error(
+      `WeCom outbound account mismatch: target belongs to account=${scoped.accountId}, current account=${params.accountId}.`,
+    );
+  }
+  if (scoped.target.chatid) {
+    return scoped.target.chatid;
+  }
+  if (scoped.target.touser) {
+    return scoped.target.touser;
+  }
+  return undefined;
+}
+
+function shouldPreferBotWsOutbound(params: {
+  cfg: ChannelOutboundContext["cfg"];
+  accountId?: string | null;
+  to: string | undefined;
+}): { preferred: boolean; accountId: string } {
+  const account = resolveOutboundAccountOrThrow({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  return {
+    preferred: !isExplicitAgentTarget(params.to) && Boolean(account.bot?.configured && account.bot.primaryTransport === "ws" && account.bot.wsConfigured),
+    accountId: account.accountId,
+  };
+}
+
+async function sendTextViaBotWs(params: {
+  cfg: ChannelOutboundContext["cfg"];
+  accountId?: string | null;
+  to: string | undefined;
+  text: string;
+}): Promise<boolean> {
+  const { preferred, accountId } = shouldPreferBotWsOutbound(params);
+  if (!preferred) {
+    return false;
+  }
+  const chatId = resolveBotWsChatTarget({
+    to: params.to,
+    accountId,
+  });
+  if (!chatId) {
+    return false;
+  }
+  const handle = getBotWsPushHandle(accountId);
+  if (!handle) {
+    throw new Error(
+      `WeCom outbound account=${accountId} is configured for Bot WS active push, but no live WS runtime is registered.`,
+    );
+  }
+  if (!handle.isConnected()) {
+    throw new Error(
+      `WeCom outbound account=${accountId} is configured for Bot WS active push, but the WS transport is not connected.`,
+    );
+  }
+  console.log(`[wecom-outbound] Sending Bot WS active message to target=${String(params.to ?? "")} chatId=${chatId} (len=${params.text.length})`);
+  await handle.sendMarkdown(chatId, params.text);
+  console.log(`[wecom-outbound] Successfully sent Bot WS active message to ${chatId}`);
+  return true;
+}
+
 export const wecomOutbound: ChannelOutboundAdapter = {
   deliveryMode: "direct",
   chunkerMode: "text",
@@ -59,9 +142,6 @@ export const wecomOutbound: ChannelOutboundAdapter = {
   sendText: async ({ cfg, to, text, accountId }: ChannelOutboundContext) => {
     // signal removed - not supported in current SDK
 
-    const agent = resolveAgentConfigOrThrow({ cfg, accountId });
-    const deliveryService = new WecomAgentDeliveryService(agent);
-
     // 体验优化：/new /reset 的“New session started”回执在 OpenClaw 核心里是英文固定文案，
     // 且通过 routeReply 走 wecom outbound（Agent 主动发送）。
     // 在 WeCom“双模式”场景下，这会造成：
@@ -93,12 +173,23 @@ export const wecomOutbound: ChannelOutboundAdapter = {
 
     console.log(`[wecom-outbound] Sending text to target=${String(to ?? "")} (len=${outgoingText.length})`);
 
+    let sentViaBotWs = false;
     try {
-      await deliveryService.sendText({
+      sentViaBotWs = await sendTextViaBotWs({
+        cfg,
+        accountId,
         to,
         text: outgoingText,
       });
-      console.log(`[wecom-outbound] Successfully sent text to ${String(to ?? "")}`);
+      if (!sentViaBotWs) {
+        const agent = resolveAgentConfigOrThrow({ cfg, accountId });
+        const deliveryService = new WecomAgentDeliveryService(agent);
+        await deliveryService.sendText({
+          to,
+          text: outgoingText,
+        });
+        console.log(`[wecom-outbound] Successfully sent Agent text to ${String(to ?? "")}`);
+      }
     } catch (err) {
       console.error(`[wecom-outbound] Failed to send text to ${String(to ?? "")}:`, err);
       throw err;
@@ -106,13 +197,17 @@ export const wecomOutbound: ChannelOutboundAdapter = {
 
     return {
       channel: "wecom",
-      messageId: `agent-${Date.now()}`,
+      messageId: `${sentViaBotWs ? "bot-ws" : "agent"}-${Date.now()}`,
       timestamp: Date.now(),
     };
   },
   sendMedia: async ({ cfg, to, text, mediaUrl, accountId }: ChannelOutboundContext) => {
     // signal removed - not supported in current SDK
 
+    const { preferred } = shouldPreferBotWsOutbound({ cfg, accountId, to });
+    if (preferred) {
+      console.log(`[wecom-outbound] Bot WS active push does not support outbound media; falling back to Agent for target=${String(to ?? "")}`);
+    }
     const agent = resolveAgentConfigOrThrow({ cfg, accountId });
     const deliveryService = new WecomAgentDeliveryService(agent);
     if (!mediaUrl) {

package/src/runtime.ts

@@ -1,7 +1,10 @@
 export {
   getAccountRuntimeSnapshot,
+  getBotWsPushHandle,
   getWecomRuntime,
   registerAccountRuntime,
+  registerBotWsPushHandle,
   setWecomRuntime,
+  unregisterBotWsPushHandle,
   unregisterAccountRuntime,
 } from "./app/index.js";

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

@@ -91,7 +91,6 @@ export function mapBotWsFrameToInboundEvent(params: {
       transport: "bot-ws",
       accountId: account.accountId,
       reqId: frame.headers.req_id,
-      passiveWindowMs: 5_000,
       raw: {
         transport: "bot-ws",
         command: frame.cmd,

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

@@ -0,0 +1,137 @@
+import { describe, expect, it, vi, afterEach } from "vitest";
+
+import { createBotWsReplyHandle } from "./reply.js";
+
+type ReplyHandleParams = Parameters<typeof createBotWsReplyHandle>[0];
+
+describe("createBotWsReplyHandle", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("uses configured placeholder content for immediate ws ack", async () => {
+    const replyStream = vi.fn().mockResolvedValue(undefined);
+    createBotWsReplyHandle({
+      client: {
+        replyStream,
+      } as unknown as ReplyHandleParams["client"],
+      frame: {
+        headers: { req_id: "req-1" },
+        body: {},
+      } as unknown as ReplyHandleParams["frame"],
+      accountId: "default",
+      placeholderContent: "正在思考...",
+    });
+
+    expect(replyStream).toHaveBeenCalledWith(
+      expect.objectContaining({
+        headers: { req_id: "req-1" },
+      }),
+      expect.any(String),
+      "正在思考...",
+      false,
+    );
+  });
+
+  it("keeps placeholder alive until the first real ws chunk arrives", async () => {
+    vi.useFakeTimers();
+
+    const replyStream = vi.fn().mockResolvedValue(undefined);
+    const handle = createBotWsReplyHandle({
+      client: {
+        replyStream,
+      } as unknown as ReplyHandleParams["client"],
+      frame: {
+        headers: { req_id: "req-keepalive" },
+        body: {},
+      } as unknown as ReplyHandleParams["frame"],
+      accountId: "default",
+      placeholderContent: "正在思考...",
+    });
+
+    await vi.advanceTimersByTimeAsync(3000);
+    expect(replyStream).toHaveBeenCalledTimes(2);
+
+    await handle.deliver({ text: "最终回复" }, { kind: "final" });
+    await vi.advanceTimersByTimeAsync(6000);
+
+    expect(replyStream).toHaveBeenCalledTimes(3);
+    expect(replyStream).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        headers: { req_id: "req-keepalive" },
+      }),
+      expect.any(String),
+      "最终回复",
+      true,
+    );
+  });
+
+  it("does not auto-send placeholder when disabled", () => {
+    const replyStream = vi.fn().mockResolvedValue(undefined);
+    createBotWsReplyHandle({
+      client: {
+        replyStream,
+      } as unknown as ReplyHandleParams["client"],
+      frame: {
+        headers: { req_id: "req-2" },
+        body: {},
+      } as unknown as ReplyHandleParams["frame"],
+      accountId: "default",
+      autoSendPlaceholder: false,
+    });
+
+    expect(replyStream).not.toHaveBeenCalled();
+  });
+
+  it("swallows expired stream update errors during delivery", async () => {
+    const expiredError = {
+      headers: { req_id: "req-expired" },
+      errcode: 846608,
+      errmsg: "stream message update expired (>6 minutes), cannot update",
+    };
+    const replyStream = vi.fn().mockRejectedValue(expiredError);
+    const onFail = vi.fn();
+    const handle = createBotWsReplyHandle({
+      client: {
+        replyStream,
+      } as unknown as ReplyHandleParams["client"],
+      frame: {
+        headers: { req_id: "req-expired" },
+        body: {},
+      } as unknown as ReplyHandleParams["frame"],
+      accountId: "default",
+      autoSendPlaceholder: false,
+      onFail,
+    });
+
+    await expect(handle.deliver({ text: "最终回复" }, { kind: "final" })).resolves.toBeUndefined();
+
+    expect(replyStream).toHaveBeenCalledTimes(1);
+    expect(onFail).toHaveBeenCalledWith(expiredError);
+  });
+
+  it.each([
+    [{ headers: { req_id: "req-invalid" }, errcode: 846605, errmsg: "invalid req_id" }],
+    [{ headers: { req_id: "req-expired" }, errcode: 846608, errmsg: "stream message update expired (>6 minutes), cannot update" }],
+  ])("does not retry error reply when the ws reply window is already closed", async (error) => {
+    const replyStream = vi.fn().mockResolvedValue(undefined);
+    const onFail = vi.fn();
+    const handle = createBotWsReplyHandle({
+      client: {
+        replyStream,
+      } as unknown as ReplyHandleParams["client"],
+      frame: {
+        headers: { req_id: String(error.headers.req_id) },
+        body: {},
+      } as unknown as ReplyHandleParams["frame"],
+      accountId: "default",
+      autoSendPlaceholder: false,
+      onFail,
+    });
+
+    await handle.fail?.(error);
+
+    expect(replyStream).not.toHaveBeenCalled();
+    expect(onFail).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -1,11 +1,45 @@
+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 {
@@ -15,6 +49,45 @@ export function createBotWsReplyHandle(params: {
     return streamId;
   };
 
+  const placeholderText = params.placeholderContent?.trim() || "⏳ 正在思考中...\n\n";
+  let streamSettled = false;
+  let placeholderInFlight = false;
+  let placeholderKeepalive: ReturnType<typeof setInterval> | undefined;
+
+  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: {
       transport: "bot-ws",
@@ -29,19 +102,36 @@ export function createBotWsReplyHandle(params: {
       },
     },
     deliver: async (payload: ReplyPayload, info) => {
-      if (payload.isReasoning) {
-        return;
-      }
+      if (payload.isReasoning) return;
+
       const text = payload.text?.trim();
-      if (!text) {
-        return;
+      if (!text) return;
+
+      settleStream();
+      try {
+        await params.client.replyStream(params.frame, resolveStreamId(), text, 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) => {
-      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);
     },
   };