@yanhaidao/wecom 2.3.12 → 2.3.13

package/README.md

@@ -102,6 +102,13 @@
 
 > 项目保持高频迭代，核心改进一览：
 
+#### v2.3.13（2026-03-13）
+
+- 🛠 **[重要修复]** `Bot WS` 现在会把“引用 + 提问”中的引用内容一起带入 Agent 上下文，不再只保留用户当前这句提问。
+- 🌊 **[重要修复]** `Bot WS` 流式回复改为按“累计全文刷新”发送，修复企业微信客户端里长回答断断续续、像被拆成多段的问题。
+- 🧩 `Bot WS` 这次显式对齐企业微信 `stream.id` 的刷新语义：后续更新会覆盖为当前完整内容，而不是只发送最新增量片段。
+- ✅ 新增 `bot-ws` 引用上下文与累计流式发送回归测试，避免后续重构回退。
+
 #### v2.3.12（2026-03-12）
 
 - 🛠 **[重要修复]** Bot WS 流式回复超 6 分钟后的 `846608 stream message update expired` 现在被识别为终态错误，不再导致进程退出。
@@ -109,6 +116,8 @@
 - 🚀 Bot WS 模式下主动文本消息优先走 WS 长连接；Agent 仅兜底文件/媒体或未启用 WS 的场景。
 - 🧯 `sdk-adapter` 为 WebSocket frame 异步处理补上显式兜底捕获，漏网异常记录为 runtime issue 而非崩溃。
 - ⏱ 回复窗口过期时占位符保活立即停止。
+- 🛠 **[重要修复]** Bot WS 模式下接收图片/文件现在使用消息体独立 `aeskey` 解密，修复之前保存密文导致 `Failed to optimize image` 的问题。
+- 🛠 **[重要修复]** 解决 Agent 模式下纯数字 UserID 被误判为部门 ID 导致的 81013 错误。在 `wecom-agent:` 作用域下，纯数字目标现在优先解析为用户。
 
 #### v2.3.11（2026-03-11）
 
@@ -473,6 +482,9 @@ openclaw channels status --deep
 **Q5: 为什么发视频给 Bot 没反应？**
 > **A:** 官方 Bot 接口**不支持接收视频**。如果您需要处理视频内容，必须配置 Agent 小微应用，由于 Agent 下行具备富媒体流承接功能，本插件会自动从底层拦截将其解码并传输给底层大模型看。
 
+**Q6: 支持个人微信吗？**
+> **A:** 支持企业微信场景下的“微信插件入口”（个人微信扫码进入企业应用对话），这不等同于“个人微信网页版协议”。您可以在个人微信中直接与企业号/应用对话，无需打开企业微信 App。
+
 ---
 
 <a id="sec-9"></a>

package/changelog/v2.3.12.md

@@ -7,10 +7,12 @@
 - 【6 分钟过期修复】🛠 **[重要修复]** `Bot WS` 现在会把企业微信 `846608 stream message update expired (>6 minutes)` 识别为回复窗口已结束的终态错误，不再继续把该错误向上抛出导致进程退出。
 - 【主动推送路由收敛】🚀 **[重要修复]** 当账号实际运行在 `Bot WS` 模式时，定时消息、heartbeat 和其他主动文本发送现在优先走 `wsClient.sendMessage()`，不再默认绕去 Agent。
 - 【WS/Agent 职责切分】🧩 `Agent` 现在主要承担两类兜底：一是账号没有启用 `Bot WS` 时的主动消息发送；二是 Bot 两种模式都不支持的文件/媒体发送。
+- 【UserID 纯数字解析修复】🛠 **[重要修复]** 解决 Agent 模式下纯数字 UserID 被误判为部门 ID 导致的图片发送失败（81013 错误）。在 `wecom-agent:` 作用域下，纯数字目标现在优先解析为用户。
 - 【未处理拒绝隔离】🧯 `sdk-adapter` 为每个 WebSocket frame 的异步处理补上显式兜底捕获；即使后续再出现漏网异常，也会记录到 runtime issue，而不是变成 `unhandledRejection` 直接带崩 OpenClaw。
 - 【占位保活收敛】⏱ 当回复窗口已经过期时，WS 占位符保活会立即停止，避免过期后继续发送流式更新。
 - 【Ack 超时兜底】⏱ SDK 5 秒回执超时 (`Reply ack timeout`) 现在也被识别为终态错误，超时后立即停止占位保活并走 `onFail` 回调，不再产生 `unhandledRejection`。
 - 【回归测试补齐】✅ 新增针对 `846608` 过期更新和 `frame handler` reject 的回归测试，确保此类异常保持非致命。
+- 【Bot WS 图片/文件解密修复】🛠 **[重要修复]** `Bot WS` 模式下接收到的图片和文件现在会使用消息体中的独立 `aeskey` 进行 AES-256-CBC 解密，修复之前直接保存密文导致 `Failed to optimize image` 的问题。`media-service.ts` 新增 `downloadEncryptedMedia()` 方法，`normalizeFirstAttachment()` 自动检测 `aesKey` 并走解密路径。
 
 ## 验证结果
 - `pnpm exec vitest -c extensions/wecom/vitest.config.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`

package/changelog/v2.3.13.md

@@ -0,0 +1,19 @@
+# OpenClaw WeCom 插件 v2.3.13 变更简报
+
+> [!TIP]
+> **Bot WS 引用上下文与流式展示修复版本**：`v2.3.13` 重点补齐企业微信 `Bot WS` 对引用消息的上下文注入，并修复长回答在客户端里显示为“断断续续碎片”的问题。
+
+## 2026-03-13（v2.3.13）
+- 【引用上下文补齐】🛠 **[重要修复]** `Bot WS` 现在会复用与 `Bot Webhook` 一致的入站正文拼装逻辑。用户通过“引用 + 提问”触发机器人时，引用内容会一并进入 Agent 上下文，不再只保留当前这句提问。
+- 【WS 流式刷新修复】🌊 **[重要修复]** `Bot WS replyStream` 现在按“累计全文刷新”发送，而不是只发送最新增量片段，修复企业微信客户端中长回答显示断断续续、像被拆成多块的问题。
+- 【协议语义对齐】🧩 这次调整显式对齐企业微信 `stream.id` 的刷新语义：同一条流式消息的后续更新会覆盖为“当前完整内容”，从而保持最终展示稳定、可连续阅读。
+- 【回归测试补齐】✅ 新增 `bot-ws` 引用上下文与累计流式发送测试，避免后续重构再次把引用消息或流式展示打回退。
+
+## 验证结果
+- `pnpm exec vitest run --config extensions/wecom/vitest.config.ts extensions/wecom/src/transport/bot-ws/inbound.test.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`
+- `pnpm exec tsc -p extensions/wecom/tsconfig.json --noEmit`
+
+## 升级提示
+- 无需新增配置，升级到 `v2.3.13` 后自动生效。
+- 如果企业微信 `WS` 推送里的 `quote.text.content` 仍然是 `[该消息类型暂不能展示]`，说明上游没有下发真实引用原文；OpenClaw 会把该占位文本带入上下文，但无法恢复企业微信未提供的原始内容。
+- 如果你之前观察到长回复在企业微信里呈现为“分段断裂”或“后段覆盖前段”，升级后会改为同一条流式消息持续刷新完整内容。

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.3.12",
+  "version": "2.3.13",
   "type": "module",
-  "description": "OpenClaw 企业微信（WeCom）插件，默认 Bot WebSocket，支持 Agent 主动发消息与多账号接入",
+  "description": "OpenClaw 企业微信（WeCom）插件，默认 Bot WebSocket，支持加密媒体解密、Agent 主动发消息与多账号接入",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/YanHaidao/wecom.git"

package/src/agent/handler.ts

@@ -566,32 +566,31 @@ async function processAgentMessage(params: {
         }
         return;
     }
-
-    const ctxPayload = core.channel.reply.finalizeInboundContext({
-        Body: body,
-        RawBody: finalContent,
-        CommandBody: finalContent,
-        Attachments: attachments.length > 0 ? attachments : undefined,
-        From: isGroup ? `wecom:group:${peerId}` : `wecom:${fromUser}`,
-        To: `wecom:${peerId}`,
-        SessionKey: route.sessionKey,
-        AccountId: route.accountId,
-        ChatType: isGroup ? "group" : "direct",
-        ConversationLabel: fromLabel,
-        SenderName: fromUser,
-        SenderId: fromUser,
-        Provider: "wecom",
-        Surface: "webchat",
-        OriginatingChannel: "wecom",
-        // 标记为 Agent 会话的回复路由目标，避免与 Bot 会话混淆：
-        // - 用于让 /new /reset 这类命令回执不被 Bot 侧策略拦截
-        // - 群聊场景也统一路由为私信触发者（与 deliver 策略一致）
-        OriginatingTo: buildAgentSessionTarget(fromUser, agent.accountId),
-        CommandAuthorized: authz.commandAuthorized ?? true,
-        MediaPath: mediaPath,
-        MediaType: mediaType,
-        MediaUrl: mediaPath,
-    });
+const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: body,
+    RawBody: finalContent,
+    CommandBody: finalContent,
+    Attachments: attachments.length > 0 ? attachments : undefined,
+    From: isGroup ? `wecom:group:${peerId}` : `wecom:user:${fromUser}`,
+    To: `wecom:user:${peerId}`,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: isGroup ? "group" : "direct",
+    ConversationLabel: fromLabel,
+    SenderName: fromUser,
+    SenderId: fromUser,
+    Provider: "wecom",
+    Surface: "webchat",
+    OriginatingChannel: "wecom",
+    // 标记为 Agent 会话的回复路由目标，避免与 Bot 会话混淆：
+    // - 用于让 /new /reset 这类命令回执不被 Bot 侧策略拦截
+    // - 群聊场景也统一路由为私信触发者（与 deliver 策略一致）
+    OriginatingTo: buildAgentSessionTarget(fromUser, agent.accountId),
+    CommandAuthorized: authz.commandAuthorized ?? true,
+    MediaPath: mediaPath,
+    MediaType: mediaType,
+    MediaUrl: mediaPath,
+});
 
     // 记录会话
     await core.channel.session.recordInboundSession({

package/src/dynamic-agent.ts

@@ -51,7 +51,8 @@ export function generateAgentId(chatType: "dm" | "group", peerId: string, accoun
 export function buildAgentSessionTarget(userId: string, accountId?: string): string {
     const normalizedUserId = String(userId).trim();
     const sanitizedAccountId = sanitizeDynamicIdPart(accountId ?? "default") || "default";
-    return `wecom-agent:${sanitizedAccountId}:${normalizedUserId}`;
+    // Always use explicit user: prefix to avoid ambiguity with numeric party IDs
+    return `wecom-agent:${sanitizedAccountId}:user:${normalizedUserId}`;
 }
 
 /**

package/src/shared/media-service.ts

@@ -2,6 +2,7 @@ import type { PluginRuntime } from "openclaw/plugin-sdk";
 
 import type { NormalizedMediaAttachment } from "./media-types.js";
 import type { UnifiedInboundEvent } from "../types/index.js";
+import { decryptWecomMediaWithMeta } from "../media.js";
 
 export class WecomMediaService {
   constructor(private readonly core: PluginRuntime) {}
@@ -15,6 +16,21 @@ export class WecomMediaService {
     };
   }
 
+  /**
+   * Download and decrypt WeCom AES-encrypted media.
+   * Bot-ws: each message carries a unique per-URL aeskey in the message body.
+   * Bot-webhook: uses the account-level EncodingAESKey.
+   * Both use AES-256-CBC with PKCS#7 padding (32-byte block), IV = key[:16].
+   */
+  async downloadEncryptedMedia(params: { url: string; aesKey: string }): Promise<NormalizedMediaAttachment> {
+    const decrypted = await decryptWecomMediaWithMeta(params.url, params.aesKey);
+    return {
+      buffer: decrypted.buffer,
+      contentType: decrypted.sourceContentType,
+      filename: decrypted.sourceFilename,
+    };
+  }
+
   async saveInboundAttachment(event: UnifiedInboundEvent, attachment: NormalizedMediaAttachment): Promise<string> {
     const saved = await this.core.channel.media.saveMediaBuffer(
       attachment.buffer,
@@ -31,6 +47,10 @@ export class WecomMediaService {
     if (!first?.remoteUrl) {
       return undefined;
     }
+    // Bot-ws media is AES-encrypted; use decryption when aesKey is present
+    if (first.aesKey) {
+      return this.downloadEncryptedMedia({ url: first.remoteUrl, aesKey: first.aesKey });
+    }
     return this.downloadRemoteMedia({ url: first.remoteUrl });
   }
 }

package/src/target.ts

@@ -35,12 +35,12 @@ export interface ScopedWecomTarget {
  * 2. 检查显式类型前缀 (party:, tag:, group:, user:)。
  * 3. 启发式回退 (无前缀时):
  *    - 以 "wr" 或 "wc" 开头 -> Chat ID (群聊)
- *    - 纯数字 -> Party ID (部门)
+ *    - 纯数字 -> 默认 Party ID (部门)；如果 preferUserForDigits 为 true 则视为 User ID
  *    - 其他 -> User ID (用户)
  * 
  * @param raw - The raw target string (e.g. "party:1", "zhangsan", "wecom:wr123")
  */
-export function resolveWecomTarget(raw: string | undefined): WecomTarget | undefined {
+export function resolveWecomTarget(raw: string | undefined, options?: { preferUserForDigits?: boolean }): WecomTarget | undefined {
     if (!raw?.trim()) return undefined;
 
     // 1. Remove standard namespace prefixes (移除标准命名空间前缀)
@@ -78,6 +78,9 @@ export function resolveWecomTarget(raw: string | undefined): WecomTarget | undef
     // 纯数字优先被视为部门 ID (Parties)，方便运维配置 (如 "1" 代表根部门)
     // 如果必须要发送给纯数字 ID 的用户，请使用显式前缀 "user:1001"
     if (/^\d+$/.test(clean)) {
+        if (options?.preferUserForDigits) {
+            return { touser: clean };
+        }
         return { toparty: clean };
     }
 
@@ -93,7 +96,9 @@ export function resolveScopedWecomTarget(raw: string | undefined, defaultAccount
     if (agentScoped) {
         const accountId = agentScoped[1]?.trim() || defaultAccountId;
         const rawTarget = agentScoped[2]?.trim() || "";
-        const target = resolveWecomTarget(rawTarget);
+        // Agent scoped targets are almost always users in a conversation context.
+        // In this scope, we prefer treating numeric IDs as User IDs to avoid 81013 errors.
+        const target = resolveWecomTarget(rawTarget, { preferUserForDigits: true });
         return target ? { accountId, target, rawTarget } : undefined;
     }
 

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

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+
+import { mapBotWsFrameToInboundEvent } from "./inbound.js";
+import type { ResolvedBotAccount } from "../../types/index.js";
+
+function createBotAccount(): ResolvedBotAccount {
+  return {
+    accountId: "haidao",
+    configured: true,
+    primaryTransport: "ws",
+    wsConfigured: true,
+    webhookConfigured: false,
+    config: {},
+    ws: {
+      botId: "bot-id",
+      secret: "secret",
+    },
+    token: "",
+    encodingAESKey: "",
+    receiveId: "",
+    botId: "bot-id",
+    secret: "secret",
+  };
+}
+
+describe("mapBotWsFrameToInboundEvent", () => {
+  it("includes quote content in text events", () => {
+    const event = mapBotWsFrameToInboundEvent({
+      account: createBotAccount(),
+      frame: {
+        cmd: "aibot_msg_callback",
+        headers: { req_id: "req-1" },
+        body: {
+          msgid: "msg-1",
+          msgtype: "text",
+          chattype: "group",
+          chatid: "group-1",
+          from: { userid: "user-1" },
+          text: { content: "@daodao 这个线索价值" },
+          quote: {
+            msgtype: "text",
+            text: { content: "原始引用内容" },
+          },
+        },
+      },
+    });
+
+    expect(event.text).toBe("@daodao 这个线索价值\n\n> 原始引用内容");
+  });
+});

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

@@ -1,6 +1,12 @@
 import type { BaseMessage, EventMessage, WsFrame } from "@wecom/aibot-node-sdk";
 
-import type { ResolvedBotAccount, UnifiedInboundEvent, WecomInboundKind } from "../../types/index.js";
+import { buildInboundBody } from "../bot-webhook/message-shape.js";
+import type {
+  ResolvedBotAccount,
+  UnifiedInboundEvent,
+  WecomBotInboundMessage,
+  WecomInboundKind,
+} from "../../types/index.js";
 
 function resolveInboundKind(message: BaseMessage | EventMessage): WecomInboundKind {
   if (message.msgtype === "event") {
@@ -24,26 +30,10 @@ function resolveInboundKind(message: BaseMessage | EventMessage): WecomInboundKi
 }
 
 function resolveEventText(message: BaseMessage | EventMessage, account: ResolvedBotAccount): string {
-  if (message.msgtype === "text") {
-    return message.text?.content ?? "";
-  }
-  if (message.msgtype === "voice") {
-    return message.voice?.content ?? "";
-  }
-  if (message.msgtype === "mixed") {
-    return (message.mixed?.msg_item ?? [])
-      .map((item: { msgtype: string; text?: { content?: string } }) =>
-        item.msgtype === "text" ? item.text?.content ?? "" : "[image]",
-      )
-      .filter(Boolean)
-      .join("\n");
-  }
-  if (message.msgtype === "image") {
-    return "[image]";
-  }
-  if (message.msgtype === "file") {
-    return "[file]";
+  if (message.msgtype !== "event") {
+    return buildInboundBody(message as WecomBotInboundMessage);
   }
+
   const event = message as EventMessage;
   if (event.event?.eventtype === "enter_chat" && account.config.welcomeText) {
     return account.config.welcomeText;

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

@@ -83,6 +83,53 @@ describe("createBotWsReplyHandle", () => {
     expect(replyStream).not.toHaveBeenCalled();
   });
 
+  it("sends cumulative content for block streaming updates", async () => {
+    const replyStream = vi.fn().mockResolvedValue(undefined);
+    const handle = createBotWsReplyHandle({
+      client: {
+        replyStream,
+      } as unknown as ReplyHandleParams["client"],
+      frame: {
+        headers: { req_id: "req-blocks" },
+        body: {},
+      } as unknown as ReplyHandleParams["frame"],
+      accountId: "default",
+      autoSendPlaceholder: false,
+    });
+
+    await handle.deliver({ text: "第一段" }, { kind: "block" });
+    await handle.deliver({ text: "第二段" }, { kind: "block" });
+    await handle.deliver({ text: "收尾" }, { kind: "final" });
+
+    expect(replyStream).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({
+        headers: { req_id: "req-blocks" },
+      }),
+      expect.any(String),
+      "第一段",
+      false,
+    );
+    expect(replyStream).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        headers: { req_id: "req-blocks" },
+      }),
+      expect.any(String),
+      "第一段\n第二段",
+      false,
+    );
+    expect(replyStream).toHaveBeenNthCalledWith(
+      3,
+      expect.objectContaining({
+        headers: { req_id: "req-blocks" },
+      }),
+      expect.any(String),
+      "第一段\n第二段\n收尾",
+      true,
+    );
+  });
+
   it("swallows expired stream update errors during delivery", async () => {
     const expiredError = {
       headers: { req_id: "req-expired" },

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

@@ -44,6 +44,7 @@ export function createBotWsReplyHandle(params: {
   onFail?: (error: unknown) => void;
 }): ReplyHandle {
   let streamId: string | undefined;
+  let accumulatedText = "";
   const resolveStreamId = () => {
     streamId ||= generateReqId("stream");
     return streamId;
@@ -107,9 +108,27 @@ export function createBotWsReplyHandle(params: {
       const text = payload.text?.trim();
       if (!text) return;
 
+      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(), text, info.kind === "final");
+        await params.client.replyStream(
+          params.frame,
+          resolveStreamId(),
+          outboundText,
+          info.kind === "final",
+        );
       } catch (error) {
         if (isTerminalReplyError(error)) {
           params.onFail?.(error);