@yanhaidao/wecom 2.3.160 → 2.3.180

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

@@ -1,7 +1,13 @@
+import {
+  generateReqId,
+  type WsFrame,
+  type BaseMessage,
+  type EventMessage,
+  type WSClient,
+} from "@wecom/aibot-node-sdk";
 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";
+import { uploadAndSendBotWsMedia } from "./media.js";
 
 const PLACEHOLDER_KEEPALIVE_MS = 3000;
 const MAX_KEEPALIVE_MS = 120 * 1000; // Force stop keepalive after 120s if ignored
@@ -32,7 +38,14 @@ function isAckTimeoutError(error: unknown): boolean {
 }
 
 function isTerminalReplyError(error: unknown): boolean {
-  return isInvalidReqIdError(error) || isExpiredStreamUpdateError(error) || isAckTimeoutError(error);
+  return (
+    isInvalidReqIdError(error) || isExpiredStreamUpdateError(error) || isAckTimeoutError(error)
+  );
+}
+
+function formatMediaFailure(mediaUrl: string, error?: string, rejectReason?: string): string {
+  const reason = rejectReason || error || "unknown";
+  return `媒体发送失败：${mediaUrl} (${reason})`;
 }
 
 // Global registry to track active keepalives by peerId
@@ -54,6 +67,7 @@ export function createBotWsReplyHandle(params: {
 }): ReplyHandle {
   let streamId: string | undefined;
   let accumulatedText = "";
+  let deferredMediaUrls: string[] = [];
   const resolveStreamId = () => {
     streamId ||= generateReqId("stream");
     return streamId;
@@ -68,11 +82,15 @@ export function createBotWsReplyHandle(params: {
   // Extract peerId for clustering handles
   const body = params.frame.body as any;
   const peerId = String(
-    (body?.chattype === "group" ? body?.chatid || body?.from?.userid : body?.from?.userid) || "unknown"
+    (body?.chattype === "group" ? body?.chatid || body?.from?.userid : body?.from?.userid) ||
+      "unknown",
   );
   const reqId = params.frame.headers.req_id || "unknown";
 
-  const isEvent = params.inboundKind === "welcome" || params.inboundKind === "event" || params.inboundKind === "template-card-event";
+  const isEvent =
+    params.inboundKind === "welcome" ||
+    params.inboundKind === "event" ||
+    params.inboundKind === "template-card-event";
 
   const stopPlaceholderKeepalive = () => {
     if (placeholderKeepalive) {
@@ -83,7 +101,7 @@ export function createBotWsReplyHandle(params: {
       clearTimeout(placeholderTimeout);
       placeholderTimeout = undefined;
     }
-    
+
     // Remove from registry
     const keepalives = activeKeepalivesByPeer.get(peerId);
     if (keepalives) {
@@ -107,7 +125,8 @@ export function createBotWsReplyHandle(params: {
   const sendPlaceholder = () => {
     if (streamSettled || placeholderInFlight || isEvent) return;
     placeholderInFlight = true;
-    params.client.replyStream(params.frame, resolveStreamId(), placeholderText, false)
+    params.client
+      .replyStream(params.frame, resolveStreamId(), placeholderText, false)
       .catch((error) => {
         if (!isTerminalReplyError(error)) {
           return;
@@ -134,13 +153,27 @@ export function createBotWsReplyHandle(params: {
     }
   };
 
+  const mergeDeferredMediaUrls = (urls: string[]): string[] => {
+    if (urls.length === 0) {
+      return deferredMediaUrls;
+    }
+    const merged = [...deferredMediaUrls];
+    for (const url of urls) {
+      if (!merged.includes(url)) {
+        merged.push(url);
+      }
+    }
+    deferredMediaUrls = merged;
+    return deferredMediaUrls;
+  };
+
   if (params.autoSendPlaceholder !== false && !isEvent) {
     sendPlaceholder();
     placeholderKeepalive = setInterval(() => {
       sendPlaceholder();
     }, PLACEHOLDER_KEEPALIVE_MS);
-    
-    // Safety net: force stop keepalive after MAX_KEEPALIVE_MS 
+
+    // Safety net: force stop keepalive after MAX_KEEPALIVE_MS
     // in case the message is completely ignored by the core and never triggers deliver/fail
     placeholderTimeout = setTimeout(() => {
       stopPlaceholderKeepalive();
@@ -183,10 +216,22 @@ export function createBotWsReplyHandle(params: {
         return;
       }
 
-      const text = payload.text?.trim();
-      if (!text) return;
+      const text = payload.text?.trim() || "";
+      const incomingMediaUrls = payload.mediaUrls || (payload.mediaUrl ? [payload.mediaUrl] : []);
+      const hasIncomingMedia = incomingMediaUrls.length > 0;
+      if (info.kind !== "final" && hasIncomingMedia) {
+        mergeDeferredMediaUrls(incomingMediaUrls);
+      }
+      const mediaUrls =
+        info.kind === "final" ? mergeDeferredMediaUrls(incomingMediaUrls) : incomingMediaUrls;
+      if (!text && mediaUrls.length === 0) {
+        return;
+      }
 
       if (info.kind === "block") {
+        if (!text) {
+          return;
+        }
         accumulatedText = accumulatedText ? `${accumulatedText}\n${text}` : text;
       }
 
@@ -199,6 +244,46 @@ export function createBotWsReplyHandle(params: {
             : text
           : accumulatedText || text;
 
+      let finalText = outboundText;
+      if (info.kind === "final" && mediaUrls.length > 0) {
+        const mediaFailures: string[] = [];
+        const mediaNotes: string[] = [];
+        let mediaSent = 0;
+        for (const mediaUrl of mediaUrls) {
+          const result = await uploadAndSendBotWsMedia({
+            wsClient: params.client,
+            chatId: peerId,
+            mediaUrl,
+          });
+          if (result.ok) {
+            mediaSent += 1;
+            if (result.downgradeNote) {
+              mediaNotes.push(result.downgradeNote);
+            }
+            continue;
+          }
+          mediaFailures.push(formatMediaFailure(mediaUrl, result.error, result.rejectReason));
+        }
+
+        if (!finalText && mediaSent > 0) {
+          finalText = "文件已发送。";
+        }
+        if (mediaFailures.length > 0) {
+          finalText = finalText
+            ? `${finalText}\n\n${mediaFailures.join("\n")}`
+            : mediaFailures.join("\n");
+        }
+        if (mediaNotes.length > 0) {
+          finalText = finalText
+            ? `${finalText}\n\n${mediaNotes.join("\n")}`
+            : mediaNotes.join("\n");
+        }
+        deferredMediaUrls = [];
+      }
+      if (!finalText) {
+        return;
+      }
+
       // Event frames do not support streaming chunks
       if (isEvent && info.kind !== "final") {
         return;
@@ -209,19 +294,19 @@ export function createBotWsReplyHandle(params: {
         if (params.inboundKind === "welcome") {
           await params.client.replyWelcome(params.frame, {
             msgtype: "text",
-            text: { content: outboundText },
+            text: { content: finalText },
           });
         } else if (isEvent) {
           // Send push message for other events
           await params.client.sendMessage(peerId, {
             msgtype: "markdown",
-            markdown: { content: outboundText },
+            markdown: { content: finalText },
           });
         } else {
           await params.client.replyStream(
             params.frame,
             resolveStreamId(),
-            outboundText,
+            finalText,
             info.kind === "final",
           );
         }
@@ -243,17 +328,20 @@ export function createBotWsReplyHandle(params: {
       }
       const message = formatErrorMessage(error);
       const text = `WeCom WS reply failed: ${message}`;
-      
+
       try {
         if (params.inboundKind === "welcome") {
-            await params.client.replyWelcome(params.frame, { msgtype: "text", text: { content: text }});
+          await params.client.replyWelcome(params.frame, {
+            msgtype: "text",
+            text: { content: text },
+          });
         } else if (isEvent) {
-            await params.client.sendMessage(peerId, {
-              msgtype: "markdown",
-              markdown: { content: text },
-            });
+          await params.client.sendMessage(peerId, {
+            msgtype: "markdown",
+            markdown: { content: text },
+          });
         } else {
-            await params.client.replyStream(params.frame, resolveStreamId(), text, true);
+          await params.client.replyStream(params.frame, resolveStreamId(), text, true);
         }
       } catch (sendError) {
         params.onFail?.(sendError);

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

@@ -5,6 +5,7 @@ const sdkMockState = vi.hoisted(() => {
     readonly handlers = new Map<string, Array<(payload: any) => void>>();
     readonly isConnected = true;
     readonly replyStream = vi.fn().mockResolvedValue(undefined);
+    readonly replyWelcome = vi.fn().mockResolvedValue(undefined);
 
     constructor(_options: unknown) {
       sdkMockState.client = this;
@@ -117,7 +118,69 @@ describe("BotWsSdkAdapter", () => {
       }),
     );
     expect(log.error).toHaveBeenCalledWith(
-      expect.stringContaining("frame handler failed account=acc-1 reqId=req-1 message=frame exploded"),
+      expect.stringContaining(
+        "frame handler failed account=acc-1 reqId=req-1 message=frame exploded",
+      ),
+    );
+    expect(unhandledRejections).toHaveLength(0);
+  });
+
+  it("short-circuits enter_chat welcome events to a static ws welcome reply", async () => {
+    process.on("unhandledRejection", onUnhandledRejection);
+
+    const runtime = {
+      account: {
+        accountId: "acc-1",
+        bot: {
+          wsConfigured: true,
+          ws: {
+            botId: "bot-1",
+            secret: "secret-1",
+          },
+          config: {
+            welcomeText: "欢迎来到 WeCom",
+          },
+        },
+      },
+      handleEvent: vi.fn().mockResolvedValue(undefined),
+      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("event", {
+      cmd: "aibot_event_callback",
+      headers: { req_id: "req-welcome" },
+      body: {
+        msgid: "msg-welcome",
+        msgtype: "event",
+        chattype: "single",
+        from: { userid: "user-1" },
+        event: { eventtype: "enter_chat" },
+      },
+    });
+
+    await waitForAsyncCallbacks();
+
+    expect(runtime.handleEvent).not.toHaveBeenCalled();
+    expect(sdkMockState.client?.replyWelcome).toHaveBeenCalledWith(
+      expect.objectContaining({
+        headers: { req_id: "req-welcome" },
+      }),
+      {
+        msgtype: "text",
+        text: { content: "欢迎来到 WeCom" },
+      },
+    );
+    expect(log.info).toHaveBeenCalledWith(
+      expect.stringContaining("static welcome delivered account=acc-1 messageId=msg-welcome"),
     );
     expect(unhandledRejections).toHaveLength(0);
   });

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

@@ -1,13 +1,18 @@
 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 AiBot, {
+  generateReqId,
+  type BaseMessage,
+  type EventMessage,
+  type WsFrame,
+} from "@wecom/aibot-node-sdk";
+import type { WecomAccountRuntime } from "../../app/account-runtime.js";
 import { registerBotWsPushHandle, unregisterBotWsPushHandle } from "../../app/index.js";
+import { clearWecomMcpAccountCache } from "../../capability/mcp/index.js";
+import type { RuntimeLogSink } from "../../types/index.js";
 import { mapBotWsFrameToInboundEvent } from "./inbound.js";
+import { uploadAndSendBotWsMedia } from "./media.js";
 import { createBotWsReplyHandle } from "./reply.js";
 import { createBotWsSessionSnapshot } from "./session.js";
-import type { WecomAccountRuntime } from "../../app/account-runtime.js";
 
 export class BotWsSdkAdapter {
   private client?: AiBot.WSClient;
@@ -32,15 +37,35 @@ export class BotWsSdkAdapter {
       botId: bot.ws.botId,
       secret: bot.ws.secret,
       logger: {
-        debug: (message, ...args) => this.log.info?.(`[wecom-ws] ${message} ${args.join(" ")}`.trim()),
-        info: (message, ...args) => this.log.info?.(`[wecom-ws] ${message} ${args.join(" ")}`.trim()),
-        warn: (message, ...args) => this.log.warn?.(`[wecom-ws] ${message} ${args.join(" ")}`.trim()),
-        error: (message, ...args) => this.log.error?.(`[wecom-ws] ${message} ${args.join(" ")}`.trim()),
+        debug: (message, ...args) =>
+          this.log.info?.(`[wecom-ws] ${message} ${args.join(" ")}`.trim()),
+        info: (message, ...args) =>
+          this.log.info?.(`[wecom-ws] ${message} ${args.join(" ")}`.trim()),
+        warn: (message, ...args) =>
+          this.log.warn?.(`[wecom-ws] ${message} ${args.join(" ")}`.trim()),
+        error: (message, ...args) =>
+          this.log.error?.(`[wecom-ws] ${message} ${args.join(" ")}`.trim()),
       },
     });
     this.client = client;
     registerBotWsPushHandle(this.runtime.account.accountId, {
       isConnected: () => client.isConnected,
+      replyCommand: async ({ cmd, body, headers }) => {
+        const result = await client.reply(
+          { headers: headers ?? { req_id: generateReqId("wecom_ws") } },
+          body ?? {},
+          cmd,
+        );
+        this.runtime.touchTransportSession("bot-ws", {
+          ownerId: this.ownerId,
+          running: true,
+          connected: client.isConnected,
+          authenticated: client.isConnected,
+          lastOutboundAt: Date.now(),
+          lastError: undefined,
+        });
+        return result as Record<string, unknown>;
+      },
       sendMarkdown: async (chatId, content) => {
         await client.sendMessage(chatId, {
           msgtype: "markdown",
@@ -55,6 +80,29 @@ export class BotWsSdkAdapter {
           lastError: undefined,
         });
       },
+      sendMedia: async ({ chatId, mediaUrl, text, mediaLocalRoots }) => {
+        const result = await uploadAndSendBotWsMedia({
+          wsClient: client,
+          chatId,
+          mediaUrl,
+          mediaLocalRoots,
+        });
+        if (result.ok && text?.trim()) {
+          await client.sendMessage(chatId, {
+            msgtype: "markdown",
+            markdown: { content: text.trim() },
+          });
+        }
+        this.runtime.touchTransportSession("bot-ws", {
+          ownerId: this.ownerId,
+          running: true,
+          connected: client.isConnected,
+          authenticated: client.isConnected,
+          lastOutboundAt: Date.now(),
+          lastError: result.ok ? undefined : result.error,
+        });
+        return result;
+      },
     });
 
     client.on("connected", () => {
@@ -82,8 +130,12 @@ export class BotWsSdkAdapter {
     });
 
     client.on("disconnected", (reason) => {
+      clearWecomMcpAccountCache(this.runtime.account.accountId);
       const normalizedReason = String(reason ?? "").toLowerCase();
-      const kicked = normalizedReason.includes("kick") || normalizedReason.includes("owner") || normalizedReason.includes("replaced");
+      const kicked =
+        normalizedReason.includes("kick") ||
+        normalizedReason.includes("owner") ||
+        normalizedReason.includes("replaced");
       this.log.warn?.(
         `[wecom-ws] disconnected account=${this.runtime.account.accountId} kicked=${String(kicked)} reason=${reason ?? "unknown"}`,
       );
@@ -109,11 +161,15 @@ export class BotWsSdkAdapter {
     });
 
     client.on("reconnecting", (attempt) => {
-      this.log.warn?.(`[wecom-ws] reconnecting account=${this.runtime.account.accountId} attempt=${attempt}`);
+      this.log.warn?.(
+        `[wecom-ws] reconnecting account=${this.runtime.account.accountId} attempt=${attempt}`,
+      );
     });
 
     client.on("error", (error) => {
-      this.log.error?.(`[wecom-ws] error account=${this.runtime.account.accountId} message=${error.message}`);
+      this.log.error?.(
+        `[wecom-ws] error account=${this.runtime.account.accountId} message=${error.message}`,
+      );
       this.runtime.updateTransportSession(
         createBotWsSessionSnapshot({
           accountId: this.runtime.account.accountId,
@@ -176,6 +232,25 @@ export class BotWsSdkAdapter {
           });
         },
       });
+
+      const staticWelcomeText =
+        event.inboundKind === "welcome" ? botAccount.config.welcomeText?.trim() : undefined;
+      if (staticWelcomeText) {
+        this.log.info?.(
+          `[wecom-ws] static welcome reply account=${this.runtime.account.accountId} messageId=${event.messageId} peer=${event.conversation.peerKind}:${event.conversation.peerId} len=${staticWelcomeText.length}`,
+        );
+        await replyHandle.deliver(
+          {
+            text: staticWelcomeText,
+          },
+          { kind: "final" },
+        );
+        this.log.info?.(
+          `[wecom-ws] static welcome delivered account=${this.runtime.account.accountId} messageId=${event.messageId}`,
+        );
+        return;
+      }
+
       await this.runtime.handleEvent(event, replyHandle);
     };
 
@@ -221,6 +296,7 @@ export class BotWsSdkAdapter {
 
   stop(): void {
     this.log.info?.(`[wecom-ws] stop account=${this.runtime.account.accountId}`);
+    clearWecomMcpAccountCache(this.runtime.account.accountId);
     unregisterBotWsPushHandle(this.runtime.account.accountId);
     this.runtime.updateTransportSession(
       createBotWsSessionSnapshot({

package/.claude/settings.local.json

@@ -1,11 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npx tsc:*)",
-      "Bash(./node_modules/.bin/tsc:*)",
-      "Bash(npm install)",
-      "Bash(npx vitest:*)",
-      "Bash(node --input-type=module -e:*)"
-    ]
-  }
-}

package/docs/update-content-fix.md

@@ -1,135 +0,0 @@
-# 企微文档批量更新修复指南
-
-## 问题背景
-
-企业微信文档 API 的 `batch_update` 接口存在以下限制：
-
-1. **索引基于快照**：所有操作的索引基于请求发送时的文档快照
-2. **原子性**：批量操作中一个失败则全部回滚
-3. **段落验证**：`insert_text` 必须指向已有 Run 元素，不能在空段落执行
-4. **版本控制**：`version` 参数用于并发控制（与最新版本差≤100）
-
-## 常见问题
-
-### ParagraphValidator cannot find p's parent
-
-**原因**：在空段落或无效位置插入内容
-
-**解决方案**：
-```typescript
-// 错误：直接在空位置插入文本
-requests: [
-  { insert_paragraph: { location: { index: 1 } } },
-  { insert_text: { location: { index: 1 }, text: "内容" } }  // ❌ 索引错误
-]
-
-// 正确：使用顺序模式或正确计算索引
-requests: [
-  { insert_paragraph: { location: { index: 1 } } },
-  { insert_text: { location: { index: 2 }, text: "内容" } }  // ✅ index+1
-]
-```
-
-### TextValidator cannot find p parent
-
-**原因**：`insert_text` 操作的目标段落在文档快照中不存在
-
-**解决方案**：每次操作前获取最新文档结构
-
-## 推荐方案
-
-### 方案 A：顺序模式（推荐，默认）
-
-```typescript
-await docClient.updateDocContent({
-  agent, docId,
-  requests: [...],
-  batchMode: false  // 默认：顺序执行，每次获取最新版本
-});
-```
-
-**优点**：
-- 可靠性高
-- 自动处理版本和索引
-- 适合复杂场景
-
-**缺点**：
-- API 调用次数较多
-
-### 方案 B：批量模式（高性能场景）
-
-```typescript
-await docClient.updateDocContent({
-  agent, docId,
-  requests: [
-    { insert_paragraph: { location: { index: 1 } } },
-    { insert_text: { location: { index: 2 }, text: "内容" } }
-  ],
-  batchMode: true,  // 批量执行，基于同一快照
-  version: 123      // 必须提供版本号
-});
-```
-
-**优点**：
-- API 调用次数少
-- 性能更好
-
-**缺点**：
-- 需要精确计算索引
-- 所有操作基于同一快照
-
-### 方案 C：使用 init_content（创建文档）
-
-```typescript
-await docClient.createDoc({
-  agent,
-  docName: "新文档",
-  docType: "doc",
-  init_content: [
-    "# 标题",
-    "第一段内容",
-    { type: "image", url: "https://..." },
-    "第二段内容"
-  ]
-});
-```
-
-**优点**：
-- 最简单可靠
-- 自动处理分段
-
-**缺点**：
-- 仅适用于创建文档
-
-## API 限制速查
-
-| 操作 | 限制 |
-|------|------|
-| 批量操作数 | 1-30 个 requests |
-| 版本差 | ≤100 |
-| 新增行 | ≤1000 |
-| 新增列 | ≤200 |
-| 单元格总数 | ≤10000 |
-| 查询范围 | 行≤1000, 列≤200 |
-
-## 错误码
-
-| 错误 | 原因 | 解决方案 |
-|------|------|----------|
-| ParagraphValidator | 段落位置无效 | 使用正确索引或顺序模式 |
-| TextValidator | 目标段落不存在 | 先创建段落或获取最新结构 |
-| DrawingValidator | 图片位置无效 | 在有效段落插入 |
-| version mismatch | 版本过旧 | 重新获取最新文档 |
-
-## 最佳实践
-
-1. **创建文档**：使用 `init_content`（最可靠）
-2. **更新文档**：使用顺序模式（`batchMode: false`，默认）
-3. **批量追加**：简单场景可用批量模式（需精确计算索引）
-4. **并发控制**：始终传递 `version` 参数
-5. **错误处理**：捕获异常并重试（最多 3 次）
-
-## 相关文档
-
-- [API 使用指南](./api-usage-guide.md)
-- [示例代码](./examples.md)