@yanhaidao/wecom 2.3.190 → 2.3.270

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,18 @@
 ## 📋 最近更新 (Changelog摘要)
 
 > 项目保持高频迭代，全面对齐甚至超越企业真实业务诉求。
-> **为保持精简，以下仅展示近期 4 次重大架构演进，完整历史版本（含全部 `v2.2.x`）请前往 [changelog/ 目录](./changelog/) 查阅。**
+> **为保持精简，以下仅展示近期 5 次重要更新，完整历史版本（含全部 `v2.2.x`）请前往 [changelog/ 目录](./changelog/) 查阅。**
+
+#### 📌 v2.3.27（2026-03-27）
+- **[重要修复] `channel add` 重新支持 WeCom guided setup** 🧭 之前有些环境下，`wecom` 虽然已经安装，却仍会在 OpenClaw 里显示成 “does not support guided setup yet”，导致无法直接通过交互式向导添加。现在插件已经对齐 OpenClaw 当前的 `setupWizard` 接口，`openclaw channels add` 会重新正常识别和进入配置流程。
+- **[重要修复] 修复 `installedCatalogById is not defined`** 🔧 部分用户在渠道添加或选择阶段会直接遇到 `ReferenceError: installedCatalogById is not defined`，表现上像是“选了渠道就报错”或“添加流程突然失效”。这一版已经修复对应的目录访问逻辑，添加流程恢复稳定。
+- **[升级兼容] 清理 OpenClaw 新版下失效的 SDK 旧入口** 📦 这次同步迁移了 `wecom` 插件里几处已经不再建议继续从 `openclaw/plugin-sdk` 根入口直接拿的旧接口，重点覆盖工具上下文、outbound 适配器和 Bot WS 媒体发送链路，升级 OpenClaw 后更不容易再出现“有的地方能跑、有的地方直接炸”的兼容问题。
+
+#### 📌 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 运行时也执行同样的动态路由逻辑，会话隔离终于统一了。
@@ -176,10 +187,6 @@
 #### 📌 v2.3.16（2026-03-16）
 - **[解析增强] 混合消息媒体正确接管** 🛠 重点修复在 `Bot WS` 通道下，用户如果发了“一张截图 + 一段文字指示”，以前容易丢掉截图或者 AI 只能看到无法查看的腾讯云临时链接。新版底层引擎将自动扫过所有的媒体节点摘取 URL 与解密 AES Key，还大模型一双慧眼。
 
-#### 📌 v2.3.15（2026-03-14）
-- **[原生资产稳定写入]** 📄 深度强化大模型创建企微相关原生存根文档/表格时的写入稳定性。执行 `init_content` 有了更强的前置图片上传清洗能力；极大程度杜绝了混发段落/文本/图片触发的企微官方 `Validator` 异常。
-- **[复杂分发目标解包]** 💬 补齐所有关于企业微信“群聊、部门、标签组”作为 `To` 目标的精确指令解析算法，保障向全公司的组织架构层级呼气 AI 报告不再报出 `81013 target invalid`。
-
 *(查看更早期关于“超时熔断代投、动态扩容矩阵”等功能的更新日志，请移步 [changelog/ 目录](./changelog/))*
 
 ---
@@ -198,7 +205,7 @@ openclaw plugins enable wecom
 
 ### 1.2 互动向导式初配 (适合个人开发者与极客)
 
-如果您不想手写繁杂的 JSON 配置文件，可以通过交互式向导快速完成最轻量的 WebSocket 长连接部署：
+如果您不想手写繁杂的 JSON 配置文件，可以通过交互式向导快速完成最轻量的 WebSocket 长连接部署。`v2.3.27` 起，`wecom` 已重新对齐 OpenClaw 当前的 guided setup 流程，`openclaw channels add` 可以直接识别并进入配置：
 
 1. 确保已启用本插件。
 2. 在终端运行添加渠道指令：
@@ -208,6 +215,10 @@ openclaw plugins enable wecom
 3. 选择下拉列表中第一顺位的：**企业微信 (WeCom)**
 4. 根据终端亮色指引，填入企微机器人对应的 `Bot ID` 及 `Secret`，机器人即可完成握手并进入可用状态。
 
+> **如果您最近刚升级 OpenClaw：**
+> - 若之前在添加渠道时看到 `wecom does not support guided setup yet`，请更新到当前版本后重试。
+> - 若之前在渠道添加阶段见过 `ReferenceError: installedCatalogById is not defined`，这一版也已一并修复。
+
 ### 1.3 生产环境顶配架构示范（Bot WS 流式交互 + Agent 私有通道兜底发送）
 
 如果您的目标不是“接进来能聊两句”，而是让团队在企业微信里长期稳定使用 AI，这套组合更接近生产环境的推荐形态：

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/changelog/v2.3.27.md

@@ -0,0 +1,33 @@
+# OpenClaw WeCom 插件 v2.3.27 变更简报
+
+> [!TIP]
+> `v2.3.27` 是一个以“升级兼容”和“接入恢复”为主的修复版本。重点解决三类真实会挡住使用的问题：第一，`channel add` 里 `wecom` 又能正常被识别和添加了；第二，修复了部分用户在配置或选择渠道时遇到的 `ReferenceError: installedCatalogById is not defined`；第三，把这轮 OpenClaw 升级后 `wecom` 插件里几处已经失效的 SDK 旧入口统一迁到了当前可用的公共接口，避免出现“有的地方能跑、有的地方一升级就炸”的割裂状态。
+
+## 2026-03-27（v2.3.27）
+- 【恢复 `channel add` 接入】**[重要修复]** 之前在 OpenClaw 的渠道添加流程里，`wecom` 虽然已经安装，但仍可能被显示成 “does not support guided setup yet”，导致用户无法直接从 `channel add` 走完接入。现在插件已经切到 OpenClaw 当前识别的 `setupWizard` 接口，`wecom` 会重新出现在正常的 guided setup 流程中。
+- 【修复 `installedCatalogById is not defined`】**[重要修复]** 某些用户在渠道选择或安装判断阶段会直接撞到 `ReferenceError: installedCatalogById is not defined`，表现上像是“选了渠道就报错”或“添加流程突然失效”。这次已经把对应的渠道目录访问逻辑改稳，不再依赖容易失效的解构引用。
+- 【迁移失效的插件 SDK 入口】OpenClaw 升级后，`wecom` 插件里原来直接从 `openclaw/plugin-sdk` 根入口拿的一些类型和能力，已经不再按旧方式导出。`v2.3.27` 已经把这几处高风险点迁到当前公开可用的子路径，重点覆盖了工具上下文、outbound 适配器和媒体发送相关接口。
+- 【修复 `wecom_mcp` 工具返回协议】随着 OpenClaw 新版工具结果协议收紧，`wecom_mcp` 这类插件工具如果还按旧格式返回，就会在注册或执行阶段出现类型或运行时不匹配。现在该工具返回结果已经补齐新版要求的 `details` 字段，和当前工具调用协议保持一致。
+- 【修复 Bot WS 媒体发送对旧导出的依赖】之前 Bot WebSocket 媒体发送链路依赖了一个在当前发布版 OpenClaw 中已经不可直接使用的媒体加载导出，升级后容易出现“代码看起来没问题，但媒体链路单独报错”的情况。现在媒体读取改为基于当前仍然公开可用的远程抓取、本地路径校验和 MIME 识别能力自行组装，兼容当前版本的 OpenClaw 发布面。
+- 【补齐严格类型下的 WS 回复头处理】随着依赖和 SDK 类型变严格，Bot WS 主动回复和命令回复链路里对 `req_id` 头部的处理更容易暴露问题。这一版顺手把回复头的兜底生成与返回值收窄一起补齐，减少升级后只在某些路径上报类型错误或运行时异常的概率。
+
+## 升级后你会直接感受到
+
+- 在 OpenClaw 里重新执行 `channel add` 时，`wecom` 不会再被误判成“不支持 guided setup”。
+- 遇到 `ReferenceError: installedCatalogById is not defined` 的用户，渠道添加和选择流程会恢复正常。
+- OpenClaw 升级后，`wecom` 插件不再那么依赖旧版 SDK 的根入口导出，单独安装或混合运行时更稳。
+- Bot WS 的媒体发送链路不再因为旧导出失效而单独掉链子。
+
+## 这次版本背后的最小理解模型
+
+把这次更新理解成三句话就够了：
+
+1. OpenClaw 的渠道接入面已经变了，`wecom` 不能再继续挂在旧的 onboarding 接口上。
+2. 插件如果直接依赖 `openclaw/plugin-sdk` 根入口里那些历史上“顺手可用”的符号，升级后迟早会踩到导出面收缩的问题。
+3. 真正稳定的兼容修复，不只是把一个 import 改过去，而是把接入流程、工具返回协议、outbound 类型和媒体链路一起对齐到当前公开接口。
+
+## 升级提示
+
+- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.27`。
+- 如果你刚升级 OpenClaw 后发现 `wecom` 在 `channel add` 里突然不能配置，或者用户侧开始报 `installedCatalogById is not defined`，这一版就是对应修复。
+- 如果你是“全局安装的 OpenClaw + 本地 `wecom` 源码插件”混合运行，升级后建议完整重启一次 gateway，确保新的 setup 和 outbound 逻辑都已生效。

package/index.test.ts

@@ -1,15 +1,19 @@
-import { describe, expect, it, vi } from "vitest";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { describe, expect, it, vi } from "vitest";
 import plugin from "./index.js";
 
 describe("wecom plugin register", () => {
   it("registers both recommended and legacy webhook route prefixes", () => {
     const registerChannel = vi.fn();
     const registerHttpRoute = vi.fn();
+    const registerTool = vi.fn();
+    const on = vi.fn();
     const api = {
       runtime: {},
       registerChannel,
       registerHttpRoute,
+      registerTool,
+      on,
     } as unknown as OpenClawPluginApi;
 
     plugin.register(api);

package/package.json

@@ -1,17 +1,30 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.3.190",
-  "type": "module",
+  "version": "2.3.270",
   "description": "OpenClaw 企业微信（WeCom）插件，默认 Bot WebSocket，支持加密媒体解密、Agent 主动发消息与多账号接入",
+  "license": "ISC",
+  "author": "YanHaidao (VX: YanHaidao)",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/YanHaidao/wecom.git"
   },
+  "type": "module",
   "publishConfig": {
     "access": "public"
   },
-  "license": "ISC",
-  "author": "YanHaidao (VX: YanHaidao)",
+  "dependencies": {
+    "@wecom/aibot-node-sdk": "^1.0.0",
+    "fast-xml-parser": "5.3.4",
+    "undici": "^7.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.8"
+  },
+  "peerDependencies": {
+    "openclaw": "^2026.3.23-2"
+  },
   "openclaw": {
     "extensions": [
       "./index.ts"
@@ -38,18 +51,5 @@
       "localPath": "extensions/wecom",
       "defaultChoice": "npm"
     }
-  },
-  "dependencies": {
-    "@wecom/aibot-node-sdk": "^1.0.0",
-    "fast-xml-parser": "5.3.4",
-    "undici": "^7.20.0"
-  },
-  "peerDependencies": {
-    "openclaw": ">=2026.2.24"
-  },
-  "devDependencies": {
-    "@types/node": "^25.2.0",
-    "typescript": "^5.9.3",
-    "vitest": "^2.1.8"
   }
 }

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 type { ReplyHandle } from "../types/index.js";
 import { WecomAccountRuntime } from "./account-runtime.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;
@@ -12,7 +15,7 @@ export type BotWsPushHandle = {
   replyCommand: (params: {
     cmd: string;
     body?: Record<string, unknown>;
-    headers?: Record<string, string>;
+    headers?: ({ req_id?: string } & Record<string, string>) | undefined;
   }) => Promise<Record<string, unknown>>;
   sendMedia: (params: {
     chatId: string;
@@ -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,90 @@ 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 +177,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/capability/mcp/tool.ts

@@ -1,4 +1,7 @@
-import type { OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import type {
+  OpenClawPluginToolContext,
+  OpenClawPluginToolFactory,
+} from "openclaw/plugin-sdk/core";
 import { resolveWecomSourceSnapshot } from "../../runtime/source-registry.js";
 import { cleanSchemaForGemini } from "./schema.js";
 import { clearWecomMcpCategoryCache, sendJsonRpc, type McpToolInfo } from "./transport.js";
@@ -12,9 +15,10 @@ type WecomMcpParams = {
 
 const BIZ_CACHE_CLEAR_ERROR_CODES = new Set([850002]);
 
-function textResult(data: unknown) {
+function textResult<TDetails>(data: TDetails) {
   return {
     content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
   };
 }
 
@@ -96,7 +100,7 @@ async function handleCall(
   return result;
 }
 
-export function createWeComMcpToolFactory() {
+export function createWeComMcpToolFactory(): OpenClawPluginToolFactory {
   return (toolContext: OpenClawPluginToolContext) => {
     if (toolContext.messageChannel !== "wecom") {
       return null;

package/src/channel.meta.test.ts

@@ -9,4 +9,8 @@ describe("wecomPlugin meta", () => {
     expect(wecomPlugin.meta.docsLabel).toBe("企业微信");
     expect(wecomPlugin.meta.selectionDocsPrefix).toBe("文档：");
   });
+
+  it("exposes a setupWizard for guided setup discovery", () => {
+    expect(wecomPlugin.setupWizard?.channel).toBe("wecom");
+  });
 });

package/src/channel.ts

@@ -1,13 +1,8 @@
-import type {
-  ChannelAccountSnapshot,
-  ChannelPlugin,
-  OpenClawConfig,
-} from "openclaw/plugin-sdk";
+import type { ChannelAccountSnapshot, ChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk";
 import {
   deleteAccountFromConfigSection,
   setAccountEnabledInConfigSection,
-} from "openclaw/plugin-sdk";
-
+} from "openclaw/plugin-sdk/core";
 import {
   DEFAULT_ACCOUNT_ID,
   listWecomAccountIds,
@@ -16,10 +11,10 @@ import {
   resolveWecomAccount,
   resolveWecomAccountConflict,
 } from "./config/index.js";
-import type { ResolvedWecomAccount } from "./types/index.js";
 import { monitorWecomProvider } from "./gateway-monitor.js";
-import { wecomOnboardingAdapter } from "./onboarding.js";
+import { wecomSetupWizard } from "./onboarding.js";
 import { wecomOutbound } from "./outbound.js";
+import type { ResolvedWecomAccount } from "./types/index.js";
 
 const meta = {
   id: "wecom",
@@ -27,22 +22,16 @@ const meta = {
   selectionLabel: "WeCom (企业微信)",
   docsPath: "/channels/wecom",
   docsLabel: "企业微信",
-  blurb:
-    "企业微信官方推荐三方插件，默认 Bot WS 配置简单，支持主动发消息与 Agent 全能力。",
+  blurb: "企业微信官方推荐三方插件，默认 Bot WS 配置简单，支持主动发消息与 Agent 全能力。",
   selectionDocsPrefix: "文档：",
   aliases: ["wechatwork", "wework", "qywx", "企微", "企业微信"],
   order: 85,
   quickstartAllowFrom: true,
 };
 
-function resolveAccountInboundPath(
-  account: ResolvedWecomAccount,
-): string | undefined {
+function resolveAccountInboundPath(account: ResolvedWecomAccount): string | undefined {
   const derivedPaths = resolveDerivedPathSummary(account.accountId);
-  if (
-    account.bot?.primaryTransport === "webhook" &&
-    account.bot.webhookConfigured
-  ) {
+  if (account.bot?.primaryTransport === "webhook" && account.bot.webhookConfigured) {
     return derivedPaths.botWebhook[0];
   }
   if (account.agent?.callbackConfigured) {
@@ -57,15 +46,13 @@ function normalizeWecomMessagingTarget(raw: string): string | undefined {
   if (/^wecom-agent:/i.test(trimmed)) {
     return trimmed;
   }
-  return (
-    trimmed.replace(/^(wecom|wechatwork|wework|qywx):/i, "").trim() || undefined
-  );
+  return trimmed.replace(/^(wecom|wechatwork|wework|qywx):/i, "").trim() || undefined;
 }
 
 export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
   id: "wecom",
   meta,
-  onboarding: wecomOnboardingAdapter,
+  setupWizard: wecomSetupWizard,
   capabilities: {
     chatTypes: ["direct", "group"],
     media: true,
@@ -88,8 +75,7 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
     listAccountIds: (cfg) => listWecomAccountIds(cfg as OpenClawConfig),
     resolveAccount: (cfg, accountId) =>
       resolveWecomAccount({ cfg: cfg as OpenClawConfig, accountId }),
-    defaultAccountId: (cfg) =>
-      resolveDefaultWecomAccountId(cfg as OpenClawConfig),
+    defaultAccountId: (cfg) => resolveDefaultWecomAccountId(cfg as OpenClawConfig),
     setAccountEnabled: ({ cfg, accountId, enabled }) =>
       setAccountEnabledInConfigSection({
         cfg: cfg as OpenClawConfig,
@@ -139,9 +125,7 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
       });
       // 与其他渠道保持一致：直接返回 allowFrom，空则允许所有人
       const allowFrom =
-        account.agent?.config.dm?.allowFrom ??
-        account.bot?.config.dm?.allowFrom ??
-        [];
+        account.agent?.config.dm?.allowFrom ?? account.bot?.config.dm?.allowFrom ?? [];
       return allowFrom.map((entry) => String(entry));
     },
     formatAllowFrom: ({ allowFrom }) =>
@@ -183,31 +167,24 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
       transport: (snapshot as { transport?: string }).transport ?? null,
       ownerId: (snapshot as { ownerId?: string }).ownerId ?? null,
       health: (snapshot as { health?: string }).health ?? "idle",
-      ownerDriftAt:
-        (snapshot as { ownerDriftAt?: number | null }).ownerDriftAt ?? null,
+      ownerDriftAt: (snapshot as { ownerDriftAt?: number | null }).ownerDriftAt ?? null,
       connected: (snapshot as { connected?: boolean }).connected,
       authenticated: (snapshot as { authenticated?: boolean }).authenticated,
       lastStartAt: snapshot.lastStartAt ?? null,
       lastStopAt: snapshot.lastStopAt ?? null,
       lastError: snapshot.lastError ?? null,
-      lastErrorAt:
-        (snapshot as { lastErrorAt?: number | null }).lastErrorAt ?? null,
+      lastErrorAt: (snapshot as { lastErrorAt?: number | null }).lastErrorAt ?? null,
       lastInboundAt: snapshot.lastInboundAt ?? null,
       lastOutboundAt: snapshot.lastOutboundAt ?? null,
       recentInboundSummary:
-        (snapshot as { recentInboundSummary?: string | null })
-          .recentInboundSummary ?? null,
+        (snapshot as { recentInboundSummary?: string | null }).recentInboundSummary ?? null,
       recentOutboundSummary:
-        (snapshot as { recentOutboundSummary?: string | null })
-          .recentOutboundSummary ?? null,
+        (snapshot as { recentOutboundSummary?: string | null }).recentOutboundSummary ?? null,
       recentIssueCategory:
-        (snapshot as { recentIssueCategory?: string | null })
-          .recentIssueCategory ?? null,
+        (snapshot as { recentIssueCategory?: string | null }).recentIssueCategory ?? null,
       recentIssueSummary:
-        (snapshot as { recentIssueSummary?: string | null })
-          .recentIssueSummary ?? null,
-      transportSessions:
-        (snapshot as { transportSessions?: string[] }).transportSessions ?? [],
+        (snapshot as { recentIssueSummary?: string | null }).recentIssueSummary ?? null,
+      transportSessions: (snapshot as { transportSessions?: string[] }).transportSessions ?? [],
       probe: snapshot.probe,
       lastProbeAt: snapshot.lastProbeAt ?? null,
     }),
@@ -224,42 +201,35 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
         configured: account.configured && !conflict,
         webhookPath: resolveAccountInboundPath(account),
         primaryTransport:
-          account.bot?.primaryTransport ??
-          (account.agent ? "agent-callback" : null),
-        transport:
-          (runtime as { transport?: string } | undefined)?.transport ?? null,
+          account.bot?.primaryTransport ?? (account.agent ? "agent-callback" : null),
+        transport: (runtime as { transport?: string } | undefined)?.transport ?? null,
         ownerId: (runtime as { ownerId?: string } | undefined)?.ownerId ?? null,
         health: (runtime as { health?: string } | undefined)?.health ?? "idle",
         ownerDriftAt:
-          (runtime as { ownerDriftAt?: number | null } | undefined)
-            ?.ownerDriftAt ?? null,
+          (runtime as { ownerDriftAt?: number | null } | undefined)?.ownerDriftAt ?? null,
         connected: (runtime as { connected?: boolean } | undefined)?.connected,
-        authenticated: (runtime as { authenticated?: boolean } | undefined)
-          ?.authenticated,
+        authenticated: (runtime as { authenticated?: boolean } | undefined)?.authenticated,
         running: runtime?.running ?? false,
         lastStartAt: runtime?.lastStartAt ?? null,
         lastStopAt: runtime?.lastStopAt ?? null,
         lastError: runtime?.lastError ?? conflict?.message ?? null,
-        lastErrorAt:
-          (runtime as { lastErrorAt?: number | null } | undefined)
-            ?.lastErrorAt ?? null,
+        lastErrorAt: (runtime as { lastErrorAt?: number | null } | undefined)?.lastErrorAt ?? null,
         lastInboundAt: runtime?.lastInboundAt ?? null,
         lastOutboundAt: runtime?.lastOutboundAt ?? null,
         recentInboundSummary:
-          (runtime as { recentInboundSummary?: string | null } | undefined)
-            ?.recentInboundSummary ?? null,
+          (runtime as { recentInboundSummary?: string | null } | undefined)?.recentInboundSummary ??
+          null,
         recentOutboundSummary:
           (runtime as { recentOutboundSummary?: string | null } | undefined)
             ?.recentOutboundSummary ?? null,
         recentIssueCategory:
-          (runtime as { recentIssueCategory?: string | null } | undefined)
-            ?.recentIssueCategory ?? null,
+          (runtime as { recentIssueCategory?: string | null } | undefined)?.recentIssueCategory ??
+          null,
         recentIssueSummary:
-          (runtime as { recentIssueSummary?: string | null } | undefined)
-            ?.recentIssueSummary ?? null,
+          (runtime as { recentIssueSummary?: string | null } | undefined)?.recentIssueSummary ??
+          null,
         transportSessions:
-          (runtime as { transportSessions?: string[] } | undefined)
-            ?.transportSessions ?? [],
+          (runtime as { transportSessions?: string[] } | undefined)?.transportSessions ?? [],
         dmPolicy: account.bot?.config.dm?.policy ?? "pairing",
       };
     },

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", () => {