@yanhaidao/wecom 2.3.190 → 2.3.260

package/.github/workflows/release.yml

@@ -96,14 +96,33 @@ jobs:
         id: notes
         run: |
           set -euo pipefail
-          CHANGELOG_FILE="changelog/v${{ steps.meta.outputs.version }}.md"
-          if [ -f "${CHANGELOG_FILE}" ]; then
+          VERSION="${{ steps.meta.outputs.version }}"
+          CHANGELOG_DIR="changelog"
+          CHANGELOG_FILE=""
+          CANDIDATES=("v${VERSION}.md")
+
+          IFS='.' read -r major minor patch <<< "${VERSION}"
+          if [[ -n "${major:-}" && -n "${minor:-}" && -n "${patch:-}" && "${patch}" =~ ^[0-9]+$ && ${#patch} -gt 2 ]]; then
+            trimmed_patch="${patch%?}"
+            CANDIDATES+=("v${major}.${minor}.${trimmed_patch}.md")
+          fi
+
+          echo "Release notes candidates:"
+          for candidate in "${CANDIDATES[@]}"; do
+            path="${CHANGELOG_DIR}/${candidate}"
+            echo " - ${path}"
+            if [[ -z "${CHANGELOG_FILE}" && -f "${path}" ]]; then
+              CHANGELOG_FILE="${path}"
+            fi
+          done
+
+          if [[ -n "${CHANGELOG_FILE}" ]]; then
             echo "Using changelog file: ${CHANGELOG_FILE}"
             cp "${CHANGELOG_FILE}" /tmp/release-body.md
           else
-            echo "Changelog file missing: ${CHANGELOG_FILE}; using fallback notes."
+            echo "No matching changelog file found; using fallback notes."
             {
-              echo "# @yanhaidao/wecom v${{ steps.meta.outputs.version }}"
+              echo "# @yanhaidao/wecom v${VERSION}"
               echo
               if [ "${{ steps.npm_check.outputs.exists }}" = "true" ]; then
                 echo "- npm publish skipped: version already exists."

package/README.md

@@ -161,7 +161,13 @@
 ## 📋 最近更新 (Changelog摘要)
 
 > 项目保持高频迭代，全面对齐甚至超越企业真实业务诉求。
-> **为保持精简，以下仅展示近期 4 次重大架构演进，完整历史版本（含全部 `v2.2.x`）请前往 [changelog/ 目录](./changelog/) 查阅。**
+> **为保持精简，以下仅展示近期 5 次重要更新，完整历史版本（含全部 `v2.2.x`）请前往 [changelog/ 目录](./changelog/) 查阅。**
+
+#### 📌 v2.3.26（2026-03-26）
+- **[重要修复] 升级 OpenClaw 后不再乱报错** 🔧 修复了新版 OpenClaw 下 `wecom` 插件容易出现的 `is not a function` 一类启动/运行错误。
+- **[回复更稳] Agent 和 Bot WS 不再乱串** ↔️ 现在是谁收到消息，就尽量由谁来回复，不再容易出现“在 Agent 里说话，结果 Bot WS 回你”的情况。
+- **[体验修复] Bot WS 发图后不再多冒一条 `Done...`** 🖼 之前常见表现是：`正在思考` -> 图片 -> 又多一条完成提示。现在最终收尾会尽量接回原来的回复链路。
+- **[占位符修复] 不会一直卡在“正在思考...”** ⏳ 如果图片或文本已经发出去了，占位符会更自然地结束，不会继续无意义地刷屏。
 
 #### 📌 v2.3.19（2026-03-19）
 - **[重要修复] Bot WS 现在也真正走 `dynamicAgents`** 🧭 之前同样开启动态路由时，不同消息链路的行为并不完全一致：Webhook / Agent 能按用户、群聊隔离，Bot WebSocket 却可能重新落回主 Agent。现在 WS 运行时也执行同样的动态路由逻辑，会话隔离终于统一了。

package/changelog/v2.3.26.md

@@ -0,0 +1,21 @@
+# OpenClaw WeCom 插件 v2.3.26 变更简报
+
+> [!TIP]
+> 这一版主要就是把最近最烦人的几类问题修顺了：升级后不再乱报错，Agent 和 Bot WS 不再乱串回复，Bot WS 发图片后不再多冒一条 `Done...`，占位符也不会一直卡着不收。
+
+## 2026-03-26（v2.3.26）
+- 修复了 OpenClaw 升级后 `wecom` 插件报 `is not a function` 的问题。之前是 SDK 导入路径没跟着新版调整，这一版已经统一修好。
+- 修复了 Agent 和 Bot WS 串回复的问题。现在是谁收到消息，就尽量由谁来回复，不再出现“在 Agent 里说话，结果 Bot WS 回你”这种情况。
+- 修复了 Bot WS 会话里发图片后的收尾问题。之前常见表现是：`正在思考` -> 图片 -> 又多一条 `Done!...`。现在最终文字会尽量接回原来的回复链路，不再额外多发一条完成提示。
+- 修复了 `message` 工具和 Bot WS 占位符不同步的问题。现在如果图片或文本已经发出去了，占位符不会还在那里一直刷“正在思考...”。
+- 顺手加强了“全局安装的 OpenClaw + 本地 wecom 插件源码”这种混合运行方式下的稳定性，开发时不容易再出现一边生效、一边不生效的割裂情况。
+
+## 升级后你会感受到
+- 升级 OpenClaw 后，`wecom` 插件不再因为导入问题直接报错。
+- Agent 和 Bot WS 同时开着时，回复会更稳地留在正确的对话里。
+- Bot WS 发图、发文件后，回复看起来更像一条完整对话，不会再碎成好几段。
+- 占位符会更自然地结束，不会一直停在“正在思考...”。
+
+## 升级提示
+- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.26`。
+- 如果你是“全局 `openclaw` + 本地 `extensions/wecom` 源码”在跑，升级后记得完整重启 gateway。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.3.190",
+  "version": "2.3.260",
   "type": "module",
   "description": "OpenClaw 企业微信（WeCom）插件，默认 Bot WebSocket，支持加密媒体解密、Agent 主动发消息与多账号接入",
   "repository": {
@@ -45,7 +45,7 @@
     "undici": "^7.20.0"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.2.24"
+    "openclaw": "^2026.3.23-2"
   },
   "devDependencies": {
     "@types/node": "^25.2.0",

package/src/agent/handler.ts

@@ -668,6 +668,8 @@ async function processAgentMessage(params: {
     source: "agent-callback",
     messageId: extractMsgId(msg) ?? undefined,
     sessionKey: route.sessionKey,
+    peerKind: isGroup ? "group" : "direct",
+    peerId,
   });
 
   // 构建上下文

package/src/app/account-runtime.ts

@@ -1,4 +1,5 @@
-import { formatErrorMessage, type OpenClawConfig, type PluginRuntime } from "openclaw/plugin-sdk";
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
+import { formatErrorMessage } from "openclaw/plugin-sdk/infra-runtime";
 import type { ResolvedRuntimeAccount } from "../config/runtime-config.js";
 import { WecomAuditLog } from "../observability/audit-log.js";
 import { WecomStatusRegistry } from "../observability/status-registry.js";
@@ -107,6 +108,9 @@ export class WecomAccountRuntime {
         );
         await replyHandle.fail?.(error);
       },
+      markExternalActivity: () => {
+        replyHandle.markExternalActivity?.();
+      },
     };
 
     try {

package/src/app/index.ts

@@ -1,10 +1,13 @@
 import type { PluginRuntime } from "openclaw/plugin-sdk";
 import { clearWecomSourceAccount } from "../runtime/source-registry.js";
 import { WecomAccountRuntime } from "./account-runtime.js";
+import type { ReplyHandle } from "../types/index.js";
 
 let runtime: PluginRuntime | null = null;
 const runtimes = new Map<string, WecomAccountRuntime>();
 const botWsPushHandles = new Map<string, BotWsPushHandle>();
+const activeBotWsReplyHandlesBySession = new Map<string, ReplyHandle>();
+const activeBotWsReplyHandlesByPeer = new Map<string, ReplyHandle>();
 
 export type BotWsPushHandle = {
   isConnected: () => boolean;
@@ -29,6 +32,28 @@ export type BotWsPushHandle = {
   }>;
 };
 
+function normalizeOptional(value: string | null | undefined): string | undefined {
+  const trimmed = String(value ?? "").trim();
+  return trimmed || undefined;
+}
+
+function normalizePeerId(value: string | null | undefined): string | undefined {
+  const trimmed = normalizeOptional(value);
+  return trimmed ? trimmed.toLowerCase() : undefined;
+}
+
+function buildSessionHandleKey(accountId: string, sessionKey: string): string {
+  return `${accountId}::session::${sessionKey}`;
+}
+
+function buildPeerHandleKey(
+  accountId: string,
+  peerKind: "direct" | "group",
+  peerId: string,
+): string {
+  return `${accountId}::peer::${peerKind}::${peerId}`;
+}
+
 export function setWecomRuntime(next: PluginRuntime): void {
   runtime = next;
 }
@@ -61,6 +86,87 @@ export function getBotWsPushHandle(accountId: string): BotWsPushHandle | undefin
   return botWsPushHandles.get(accountId);
 }
 
+export function registerActiveBotWsReplyHandle(params: {
+  accountId: string;
+  sessionKey?: string | null;
+  peerKind?: "direct" | "group" | null;
+  peerId?: string | null;
+  handle: ReplyHandle;
+}): void {
+  const accountId = normalizeOptional(params.accountId);
+  const sessionKey = normalizeOptional(params.sessionKey);
+  const peerId = normalizePeerId(params.peerId);
+  if (!accountId) {
+    return;
+  }
+  if (sessionKey) {
+    activeBotWsReplyHandlesBySession.set(buildSessionHandleKey(accountId, sessionKey), params.handle);
+  }
+  if ((params.peerKind === "direct" || params.peerKind === "group") && peerId) {
+    activeBotWsReplyHandlesByPeer.set(
+      buildPeerHandleKey(accountId, params.peerKind, peerId),
+      params.handle,
+    );
+  }
+}
+
+export function getActiveBotWsReplyHandle(params: {
+  accountId: string;
+  sessionKey?: string | null;
+  peerKind?: "direct" | "group" | null;
+  peerId?: string | null;
+}): ReplyHandle | undefined {
+  const accountId = normalizeOptional(params.accountId);
+  const sessionKey = normalizeOptional(params.sessionKey);
+  const peerId = normalizePeerId(params.peerId);
+  if (!accountId) {
+    return undefined;
+  }
+  if (sessionKey) {
+    const handle = activeBotWsReplyHandlesBySession.get(
+      buildSessionHandleKey(accountId, sessionKey),
+    );
+    if (handle) {
+      return handle;
+    }
+  }
+  if ((params.peerKind === "direct" || params.peerKind === "group") && peerId) {
+    return activeBotWsReplyHandlesByPeer.get(
+      buildPeerHandleKey(accountId, params.peerKind, peerId),
+    );
+  }
+  return undefined;
+}
+
+export function unregisterActiveBotWsReplyHandle(params: {
+  accountId: string;
+  sessionKey?: string | null;
+  peerKind?: "direct" | "group" | null;
+  peerId?: string | null;
+  handle?: ReplyHandle;
+}): void {
+  const accountId = normalizeOptional(params.accountId);
+  const sessionKey = normalizeOptional(params.sessionKey);
+  const peerId = normalizePeerId(params.peerId);
+  if (!accountId) {
+    return;
+  }
+  if (sessionKey) {
+    const key = buildSessionHandleKey(accountId, sessionKey);
+    const current = activeBotWsReplyHandlesBySession.get(key);
+    if (!params.handle || current === params.handle) {
+      activeBotWsReplyHandlesBySession.delete(key);
+    }
+  }
+  if ((params.peerKind === "direct" || params.peerKind === "group") && peerId) {
+    const key = buildPeerHandleKey(accountId, params.peerKind, peerId);
+    const current = activeBotWsReplyHandlesByPeer.get(key);
+    if (!params.handle || current === params.handle) {
+      activeBotWsReplyHandlesByPeer.delete(key);
+    }
+  }
+}
+
 export function unregisterBotWsPushHandle(accountId: string): void {
   botWsPushHandles.delete(accountId);
 }
@@ -68,6 +174,16 @@ export function unregisterBotWsPushHandle(accountId: string): void {
 export function unregisterAccountRuntime(accountId: string): void {
   runtimes.delete(accountId);
   botWsPushHandles.delete(accountId);
+  for (const key of activeBotWsReplyHandlesBySession.keys()) {
+    if (key.startsWith(`${accountId}::`)) {
+      activeBotWsReplyHandlesBySession.delete(key);
+    }
+  }
+  for (const key of activeBotWsReplyHandlesByPeer.keys()) {
+    if (key.startsWith(`${accountId}::`)) {
+      activeBotWsReplyHandlesByPeer.delete(key);
+    }
+  }
   clearWecomSourceAccount(accountId);
   console.log(`[wecom-runtime] unregister account=${accountId}`);
 }

package/src/channel.ts

@@ -6,7 +6,7 @@ import type {
 import {
   deleteAccountFromConfigSection,
   setAccountEnabledInConfigSection,
-} from "openclaw/plugin-sdk";
+} from "openclaw/plugin-sdk/core";
 
 import {
   DEFAULT_ACCOUNT_ID,

package/src/config/media.test.ts

@@ -1,7 +1,7 @@
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/infra-runtime";
 import { resolveWecomMediaMaxBytes, resolveWecomMergedMediaLocalRoots } from "./media.js";
 
 describe("resolveWecomMergedMediaLocalRoots", () => {

package/src/config/media.ts

@@ -1,10 +1,8 @@
 import os from "node:os";
 import path from "node:path";
-import {
-  resolveChannelMediaMaxBytes,
-  resolvePreferredOpenClawTmpDir,
-  type OpenClawConfig,
-} from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/infra-runtime";
+import { resolveChannelMediaMaxBytes } from "openclaw/plugin-sdk/media-runtime";
 
 // 默认给一个相对“够用”的上限（80MB），避免视频/较大文件频繁触发失败。
 // 仍保留上限以防止恶意大文件把进程内存打爆（下载实现会读入内存再保存）。

package/src/context-store.ts

@@ -0,0 +1,264 @@
+/**
+ * Context store for WeCom Bot WS proactive push.
+ *
+ * Similar to Weixin's contextToken mechanism, we need to track:
+ * - Which accountId has active sessions with which peerId
+ * - The contextToken for routing outbound messages
+ */
+
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+// Simple logger
+const logger = {
+  info: (...args: unknown[]) => console.log('[wecom-context]', ...args),
+  warn: (...args: unknown[]) => console.warn('[wecom-context]', ...args),
+  debug: (...args: unknown[]) => process.env.DEBUG && console.log('[wecom-context]', ...args),
+};
+
+type PeerKind = "direct" | "group";
+
+type StoredPeerContext = {
+  contextToken: string;
+  peerKind: PeerKind;
+  lastSeen: number;
+};
+
+type ResolvedPeerContext = StoredPeerContext & {
+  accountId: string;
+  peerId: string;
+};
+
+// In-memory store: accountId -> peerId -> context info
+const peerContextStore = new Map<string, Map<string, StoredPeerContext>>();
+
+// Reverse lookup: peerId -> accountId (for routing outbound)
+const peerToAccountMap = new Map<string, string>();
+const contextTokenToPeerMap = new Map<string, ResolvedPeerContext>();
+
+function resolveStateDir(): string {
+  return process.env.OPENCLAW_STATE_DIR || path.join(process.env.HOME || "/tmp", ".openclaw");
+}
+
+function resolveContextFilePath(accountId: string): string {
+  return path.join(
+    resolveStateDir(),
+    "wecom",
+    "context",
+    `${accountId}.json`
+  );
+}
+
+/** Persist peer contexts for an account to disk */
+function persistContexts(accountId: string): void {
+  const peerMap = peerContextStore.get(accountId);
+  if (!peerMap) return;
+
+  const data: Record<string, StoredPeerContext> = {};
+  for (const [peerId, info] of peerMap) {
+    data[peerId] = info;
+  }
+
+  const filePath = resolveContextFilePath(accountId);
+  try {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 0), "utf-8");
+  } catch (err) {
+    logger.warn?.(`persistContexts: failed to write ${filePath}: ${String(err)}`);
+  }
+}
+
+function normalizeContextToken(value: unknown): string | undefined {
+  const token = typeof value === "string" ? value.trim() : "";
+  return token || undefined;
+}
+
+function normalizePeerKind(value: unknown): PeerKind {
+  return value === "group" ? "group" : "direct";
+}
+
+function registerPeerContext(accountId: string, peerId: string, info: StoredPeerContext): void {
+  let peerMap = peerContextStore.get(accountId);
+  if (!peerMap) {
+    peerMap = new Map();
+    peerContextStore.set(accountId, peerMap);
+  }
+
+  const previous = peerMap.get(peerId);
+  if (previous?.contextToken && previous.contextToken !== info.contextToken) {
+    contextTokenToPeerMap.delete(previous.contextToken);
+  }
+
+  peerMap.set(peerId, info);
+  peerToAccountMap.set(peerId, accountId);
+  contextTokenToPeerMap.set(info.contextToken, {
+    accountId,
+    peerId,
+    ...info,
+  });
+}
+
+function resolveStoredPeerContext(
+  accountId: string,
+  peerId: string,
+  params: {
+    contextToken?: string;
+    peerKind?: PeerKind;
+    lastSeen?: number;
+  },
+): StoredPeerContext {
+  const existing = peerContextStore.get(accountId)?.get(peerId);
+  return {
+    contextToken:
+      normalizeContextToken(params.contextToken) ??
+      existing?.contextToken ??
+      randomUUID(),
+    peerKind: params.peerKind ?? existing?.peerKind ?? "direct",
+    lastSeen: params.lastSeen ?? Date.now(),
+  };
+}
+
+/** Restore persisted peer contexts for an account */
+export function restorePeerContexts(accountId: string): void {
+  const filePath = resolveContextFilePath(accountId);
+  try {
+    if (!fs.existsSync(filePath)) return;
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const data = JSON.parse(raw) as Record<
+      string,
+      {
+        contextToken?: string;
+        peerKind?: string;
+        lastSeen?: number;
+      }
+    >;
+
+    const peerMap = new Map<string, StoredPeerContext>();
+    let count = 0;
+    let mutated = false;
+    for (const [peerId, info] of Object.entries(data)) {
+      const normalized: StoredPeerContext = {
+        contextToken: normalizeContextToken(info?.contextToken) ?? randomUUID(),
+        peerKind: normalizePeerKind(info?.peerKind),
+        lastSeen:
+          typeof info?.lastSeen === "number" && Number.isFinite(info.lastSeen)
+            ? info.lastSeen
+            : Date.now(),
+      };
+      peerMap.set(peerId, normalized);
+      peerToAccountMap.set(peerId, accountId);
+      contextTokenToPeerMap.set(normalized.contextToken, {
+        accountId,
+        peerId,
+        ...normalized,
+      });
+      if (
+        normalized.contextToken !== info?.contextToken ||
+        normalized.peerKind !== info?.peerKind ||
+        normalized.lastSeen !== info?.lastSeen
+      ) {
+        mutated = true;
+      }
+      count++;
+    }
+    peerContextStore.set(accountId, peerMap);
+    if (mutated) {
+      persistContexts(accountId);
+    }
+    logger.info?.(`restorePeerContexts: restored ${count} peers for account=${accountId}`);
+  } catch (err) {
+    logger.warn?.(`restorePeerContexts: failed to read ${filePath}: ${String(err)}`);
+  }
+}
+
+/** Store context for a peer (called on inbound message) */
+export function setPeerContext(
+  accountId: string,
+  peerId: string,
+  options?: {
+    contextToken?: string;
+    peerKind?: PeerKind;
+    lastSeen?: number;
+  },
+): string {
+  const resolved = resolveStoredPeerContext(accountId, peerId, options ?? {});
+  registerPeerContext(accountId, peerId, resolved);
+
+  // Persist to disk (debounced would be better, but simple for now)
+  persistContexts(accountId);
+
+  logger.debug?.(
+    `setPeerContext: accountId=${accountId} peerId=${peerId} token=${resolved.contextToken} kind=${resolved.peerKind}`,
+  );
+  return resolved.contextToken;
+}
+
+/** Get the accountId that has an active session with a peer */
+export function getAccountIdByPeer(peerId: string): string | undefined {
+  return peerToAccountMap.get(peerId);
+}
+
+/** Get the most recent peerId for an account (for proactive push) */
+export function getRecentPeerForAccount(accountId: string, maxAgeMs = 30 * 60 * 1000): string | undefined {
+  const peerMap = peerContextStore.get(accountId);
+  if (!peerMap) return undefined;
+
+  let mostRecent: { peerId: string; lastSeen: number } | undefined;
+
+  for (const [peerId, info] of peerMap) {
+    if (Date.now() - info.lastSeen > maxAgeMs) continue;
+    if (!mostRecent || info.lastSeen > mostRecent.lastSeen) {
+      mostRecent = { peerId, lastSeen: info.lastSeen };
+    }
+  }
+
+  return mostRecent?.peerId;
+}
+
+/** Get context token for a peer */
+export function getPeerContextToken(accountId: string, peerId: string): string | undefined {
+  const peerMap = peerContextStore.get(accountId);
+  return peerMap?.get(peerId)?.contextToken;
+}
+
+/** Resolve a peer context from a context token. */
+export function getPeerContextByToken(contextToken: string): ResolvedPeerContext | undefined {
+  return contextTokenToPeerMap.get(contextToken);
+}
+
+/** Resolve accountId from a context token. */
+export function getAccountIdByContextToken(contextToken: string): string | undefined {
+  return contextTokenToPeerMap.get(contextToken)?.accountId;
+}
+
+/** Check if we have an active session for routing */
+export function hasActiveSession(accountId: string, peerId: string, maxAgeMs = 30 * 60 * 1000): boolean {
+  const peerMap = peerContextStore.get(accountId);
+  if (!peerMap) return false;
+
+  const info = peerMap.get(peerId);
+  if (!info) return false;
+
+  return Date.now() - info.lastSeen < maxAgeMs;
+}
+
+/** Clear all contexts for an account */
+export function clearPeerContexts(accountId: string): void {
+  const peerMap = peerContextStore.get(accountId);
+  if (peerMap) {
+    for (const [peerId, info] of peerMap) {
+      peerToAccountMap.delete(peerId);
+      contextTokenToPeerMap.delete(info.contextToken);
+    }
+  }
+  peerContextStore.delete(accountId);
+
+  const filePath = resolveContextFilePath(accountId);
+  try {
+    if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+  } catch (err) {
+    logger.warn?.(`clearPeerContexts: failed to remove ${filePath}`);
+  }
+}

package/src/onboarding.ts

@@ -8,7 +8,7 @@ import type {
     OpenClawConfig,
     WizardPrompter,
 } from "openclaw/plugin-sdk";
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/routing";
 import { listWecomAccountIds, resolveDefaultWecomAccountId, resolveWecomAccount, resolveWecomAccounts } from "./config/index.js";
 import type { WecomConfig, WecomBotConfig, WecomAgentConfig, WecomDmConfig, WecomAccountConfig } from "./types/index.js";