@wecom/wecom-openclaw-plugin 1.0.12-beta.0 → 1.0.12-beta.2

package/dist/index.cjs.js

@@ -10,8 +10,8 @@ var fs = require('node:fs/promises');
 var path = require('node:path');
 var os = require('node:os');
 var node_url = require('node:url');
-var url = require('url');
 var fileType = require('file-type');
+var node_fs = require('node:fs');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function _interopNamespaceDefault(e) {
@@ -416,10 +416,6 @@ const MEDIA_DOCUMENT_PLACEHOLDER = "<media:document>";
 const MCP_GET_CONFIG_CMD = "aibot_get_mcp_config";
 /** MCP 配置拉取超时时间（毫秒） */
 const MCP_CONFIG_FETCH_TIMEOUT_MS = 15000;
-const __filename$1 = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs.js', document.baseURI).href)));
-const __dirname$1 = path$1.dirname(__filename$1);
-const PLUGIN_JSON_FILENAME = "openclaw.plugin.json";
-path$1.resolve(path$1.join(__dirname$1, "../", PLUGIN_JSON_FILENAME));
 // ============================================================================
 // 默认值
 // ============================================================================
@@ -586,7 +582,7 @@ async function sendWeComReply(params) {
     }
     // 使用 SDK 的 replyStream 方法发送消息，带超时保护
     await withTimeout(wsClient.replyStream(frame, streamId, text, finish), REPLY_SEND_TIMEOUT_MS, `Reply send timed out (streamId=${streamId})`);
-    runtime.log?.(`[plugin -> server] streamId=${streamId}, finish=${finish}, text=${text}`);
+    runtime.log?.(`[plugin -> server] streamId=${streamId}, finish=${finish}`);
     return streamId;
 }
 
@@ -1577,140 +1573,6 @@ async function cleanupAccount(accountId) {
     }
 }
 
-/**
- * MCP 配置拉取与持久化模块
- *
- * 负责:
- * - 通过 WSClient 发送 aibot_get_mcp_config 请求
- * - 解析服务端响应,提取 MCP 配置(url、type、is_authed)
- * - 将配置写入 openclaw.plugin.json 的 wecomMcp 字段
- */
-// ============================================================================
-// MCP 配置拉取
-// ============================================================================
-/**
- * 通过 WSClient 发送 aibot_get_mcp_config 命令,获取 MCP 配置
- *
- * @param wsClient - 已认证的 WSClient 实例
- * @returns MCP 配置(url、type、is_authed)
- * @throws 响应错误码非 0 或缺少 url 字段时抛出错误
- */
-async function fetchMcpConfig(wsClient) {
-    const biz_type = "doc";
-    const reqId = aibotNodeSdk.generateReqId("mcp_config");
-    // 通过 reply 方法发送自定义命令
-    const response = await withTimeout(wsClient.reply({ headers: { req_id: reqId } }, { biz_type }, MCP_GET_CONFIG_CMD), MCP_CONFIG_FETCH_TIMEOUT_MS, `MCP config fetch timed out after ${MCP_CONFIG_FETCH_TIMEOUT_MS}ms`);
-    // 校验响应错误码
-    if (response.errcode && response.errcode !== 0) {
-        throw new Error(`MCP config request failed: errcode=${response.errcode}, errmsg=${response.errmsg ?? "unknown"}`);
-    }
-    // 提取并校验 body
-    const body = response.body;
-    if (!body?.url) {
-        throw new Error("MCP config response missing required 'url' field");
-    }
-    return {
-        biz_type,
-        url: body.url,
-        type: body.type,
-        is_authed: body.is_authed,
-    };
-}
-// ============================================================================
-// 配置持久化
-// ============================================================================
-/**
- * 将 MCP 配置写入 openclaw.plugin.json 的 mcpConfig 字段
- *
- * 使用 OpenClaw SDK 提供的文件锁和原子写入,保证并发安全。
- * 配置格式: { mcpConfig: { [type]: { type, url } } }
- * 示例: { "mcpConfig": { "doc": { "type": "streamable-http", "url": "..." } } }
- *
- * @param config - MCP 配置
- * @param runtime - 运行时环境
- */
-async function saveMcpConfigToPluginJson(config, runtime) {
-    //   const pluginJsonPath = PLUGIN_JSON_PATH;
-    // 获取绝对路径并写入到配置文件
-    //   const absolutePath = path.resolve(pluginJsonPath);
-    const wecomConfigDir = path$1.join(os$1.homedir(), ".openclaw", "wecomConfig");
-    const wecomConfigPath = path$1.join(wecomConfigDir, "config.json");
-    //   // 写入 wecom 配置文件
-    //   try {
-    //     const lockOptions = {
-    //       stale: 60_000,
-    //       retries: {
-    //         retries: 3,
-    //         factor: 1.35,
-    //         minTimeout: 8,
-    //         maxTimeout: 200,
-    //         randomize: true,
-    //       },
-    //     };
-    //     await withFileLock(wecomConfigPath, lockOptions, async () => {
-    //       const { value: wecomConfig } = await readJsonFileWithFallback<Record<string, unknown>>(
-    //         wecomConfigPath,
-    //         {},
-    //       );
-    //       wecomConfig.pluginConfigPath = absolutePath;
-    //       await writeJsonFileAtomically(wecomConfigPath, wecomConfig);
-    //       runtime.log?.(`[WeCom] Plugin config path saved to ${wecomConfigPath}`);
-    //     });
-    //   } catch (err) {
-    //     runtime.error?.(`[WeCom] Failed to save plugin config path: ${String(err)}`);
-    //   }
-    const lockOptions = {
-        stale: 60000, // 60秒锁过期
-        retries: {
-            retries: 6,
-            factor: 1.35,
-            minTimeout: 8,
-            maxTimeout: 1200,
-            randomize: true,
-        },
-    };
-    await pluginSdk.withFileLock(wecomConfigPath, lockOptions, async () => {
-        // 读取现有配置(不存在时使用空对象)
-        const { value: pluginJson } = await pluginSdk.readJsonFileWithFallback(wecomConfigPath, {});
-        // 确保 mcpConfig 字段存在且为对象
-        if (!pluginJson.mcpConfig || typeof pluginJson.mcpConfig !== 'object') {
-            pluginJson.mcpConfig = {};
-        }
-        // 使用 type 作为键存储配置
-        const typeKey = config.biz_type || 'default';
-        pluginJson.mcpConfig[typeKey] = {
-            type: config.type,
-            url: config.url,
-        };
-        // 原子写入
-        await pluginSdk.writeJsonFileAtomically(wecomConfigPath, pluginJson);
-        runtime.log?.(`[WeCom] MCP config saved to ${wecomConfigPath}`);
-    });
-}
-// ============================================================================
-// 组合入口
-// ============================================================================
-/**
- * 拉取 MCP 配置并持久化到 openclaw.plugin.json
- *
- * 认证成功后调用。失败仅记录日志,不影响 WebSocket 消息正常收发。
- *
- * @param wsClient - 已认证的 WSClient 实例
- * @param accountId - 账户 ID(用于日志)
- * @param runtime - 运行时环境(用于日志)
- */
-async function fetchAndSaveMcpConfig(wsClient, accountId, runtime) {
-    try {
-        runtime.log?.(`[${accountId}] Fetching MCP config...`);
-        const config = await fetchMcpConfig(wsClient);
-        runtime.log?.(`[${accountId}] MCP config fetched: url=${config.url}, type=${config.type ?? "N/A"}, is_authed=${config.is_authed ?? "N/A"}`);
-        await saveMcpConfigToPluginJson(config, runtime);
-    }
-    catch (err) {
-        runtime.error?.(`[${accountId}] Failed to fetch/save MCP config: ${String(err)}`);
-    }
-}
-
 /**
  * 企业微信 WebSocket 监控器主模块
  *
@@ -1992,7 +1854,7 @@ async function routeAndDispatchMessage(params) {
             dispatcherOptions: {
                 deliver: async (payload, info) => {
                     state.deliverCalled = true;
-                    runtime.log?.(`[openclaw -> plugin] kind=${info.kind}, text=${payload.text ?? ''}, mediaUrl=${payload.mediaUrl ?? ''}, mediaUrls=${JSON.stringify(payload.mediaUrls ?? [])}`);
+                    // runtime.log?.(`[openclaw -> plugin] kind=${info.kind}, text=${payload.text ?? ''}, mediaUrl=${payload.mediaUrl ?? ''}, mediaUrls=${JSON.stringify(payload.mediaUrls ?? [])}`);
                     // 累积文本
                     if (payload.text) {
                         accumulateText(state, payload.text);
@@ -2140,7 +2002,7 @@ async function processWeComMessage(params) {
     }
     // Step 7: 构建上下文并路由到核心处理流程（带整体超时保护）
     const ctxPayload = buildMessageContext(frame, account, config, text, mediaList, quoteContent);
-    runtime.log?.(`[plugin -> openclaw] body=${text}, mediaPaths=${JSON.stringify(mediaList.map(m => m.path))}${quoteContent ? `, quote=${quoteContent}` : ''}`);
+    // runtime.log?.(`[plugin -> openclaw] body=${text}, mediaPaths=${JSON.stringify(mediaList.map(m => m.path))}${quoteContent ? `, quote=${quoteContent}` : ''}`);
     try {
         await withTimeout(routeAndDispatchMessage({
             ctxPayload,
@@ -2239,8 +2101,6 @@ async function monitorWeComProvider(options) {
         wsClient.on("authenticated", () => {
             runtime.log?.(`[${account.accountId}] Authentication successful`);
             setWeComWebSocket(account.accountId, wsClient);
-            // 认证成功后自动拉取 MCP 配置（异步，失败不影响主流程）
-            fetchAndSaveMcpConfig(wsClient, account.accountId, runtime);
         });
         // 监听断开事件
         wsClient.on("disconnected", (reason) => {
@@ -2775,6 +2635,713 @@ const wecomPlugin = {
     },
 };
 
+/** 从 package.json 中读取版本号，兼容打包产物和直接运行 .ts 两种场景 */
+const getVersion = () => {
+    try {
+        // ESM 环境使用 import.meta.url，CJS 环境使用全局 __dirname
+        const currentDir = path.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs.js', document.baseURI).href))));
+        // 直接运行 .ts 时在 src/ 下，打包后在 dist/ 下，都向上一级找 package.json
+        const pkgPath = path.resolve(currentDir, "..", "package.json");
+        const pkg = JSON.parse(node_fs.readFileSync(pkgPath, "utf-8"));
+        return pkg.version ?? "";
+    }
+    catch {
+        return "";
+    }
+};
+/** 插件版本号，来源于 package.json */
+const PLUGIN_VERSION = getVersion();
+
+/**
+ * MCP Streamable HTTP 传输层模块
+ *
+ * 负责:
+ * - MCP JSON-RPC over HTTP 通信（发送请求、解析响应）
+ * - Streamable HTTP session 生命周期管理（initialize 握手 → Mcp-Session-Id 维护 → 失效重建）
+ * - 自动检测无状态 Server：如果 initialize 响应未返回 Mcp-Session-Id，
+ *   则标记为无状态模式，后续请求跳过握手和 session 管理
+ * - SSE 流式响应解析
+ * - MCP 配置运行时缓存（通过 WSClient 拉取 URL 并缓存在内存中）
+ */
+// ============================================================================
+// 内部状态
+// ============================================================================
+/** HTTP 请求超时时间（毫秒） */
+const HTTP_REQUEST_TIMEOUT_MS = 30000;
+/** 日志前缀 */
+const LOG_TAG = "[mcp]";
+/**
+ * MCP JSON-RPC 错误
+ *
+ * 携带服务端返回的 JSON-RPC error.code，
+ * 用于上层按错误码进行差异化处理（如特定错误码触发缓存清理）。
+ */
+class McpRpcError extends Error {
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = "McpRpcError";
+    }
+}
+/**
+ * MCP HTTP 错误
+ *
+ * 携带 HTTP 状态码，用于精确判断 session 失效（404）等场景，
+ * 避免通过字符串匹配 "404" 导致的误判。
+ */
+class McpHttpError extends Error {
+    constructor(statusCode, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = "McpHttpError";
+    }
+}
+/**
+ * 需要清理缓存的 JSON-RPC 错误码集合
+ *
+ * 当 MCP Server 返回以下错误码时，说明服务端状态已发生变化（如配置变更、
+ * 服务重启等），需要清理对应 category 的全部缓存，确保下次请求重新
+ * 拉取配置并重建会话。
+ *
+ * - -32001: 服务不可用（Server Unavailable）
+ * - -32002: 配置已变更（Config Changed）
+ * - -32003: 认证失败（Auth Failed）
+ */
+const CACHE_CLEAR_ERROR_CODES = new Set([-32001, -32002, -32003]);
+/** MCP 配置缓存：category → response.body（完整配置） */
+const mcpConfigCache = new Map();
+/** Streamable HTTP 会话缓存：category → session */
+const mcpSessionCache = new Map();
+/** 已确认为无状态的 MCP Server 品类集合（跳过后续握手） */
+const statelessCategories = new Set();
+/** 正在进行中的 initialize 请求（防止并发重复初始化），key 为 category */
+const inflightInitRequests = new Map();
+// ============================================================================
+// MCP 配置拉取与缓存
+// ============================================================================
+/**
+ * 通过 WSClient 拉取指定 category 的 MCP 完整配置
+ *
+ * @param category - MCP 品类名称，如 doc、contact
+ * @returns 完整的 response.body 配置对象（至少包含 url 字段）
+ */
+async function fetchMcpConfig(category) {
+    const wsClient = getWeComWebSocket(pluginSdk.DEFAULT_ACCOUNT_ID);
+    if (!wsClient) {
+        throw new Error("WSClient 未连接，无法拉取 MCP 配置");
+    }
+    const reqId = aibotNodeSdk.generateReqId("mcp_config");
+    const response = await withTimeout(wsClient.reply({ headers: { req_id: reqId } }, { biz_type: category, plugin_version: PLUGIN_VERSION }, MCP_GET_CONFIG_CMD), MCP_CONFIG_FETCH_TIMEOUT_MS, `MCP config fetch for "${category}" timed out after ${MCP_CONFIG_FETCH_TIMEOUT_MS}ms`);
+    if (response.errcode !== undefined && response.errcode !== 0) {
+        const errMsg = `MCP 配置请求失败: errcode=${response.errcode}, errmsg=${response.errmsg ?? "unknown"}`;
+        console.error(`${LOG_TAG} ${errMsg}`);
+        throw new Error(errMsg);
+    }
+    const body = response.body;
+    if (!body?.url) {
+        throw new Error(`MCP 配置响应缺少 url 字段 (category="${category}")`);
+    }
+    console.log(`${LOG_TAG} 配置拉取成功 (category="${category}")`);
+    return body;
+}
+/**
+ * 获取指定品类的 MCP Server URL
+ *
+ * 优先从内存缓存中读取，未命中时通过 WSClient 拉取并缓存。
+ *
+ * @param category - MCP 品类名称
+ * @returns MCP Server URL
+ */
+async function getMcpUrl(category) {
+    // 查内存缓存
+    const cached = mcpConfigCache.get(category);
+    if (cached)
+        return cached.url;
+    // 缓存未命中，通过 WSClient 拉取
+    const body = await fetchMcpConfig(category);
+    // 写入缓存
+    mcpConfigCache.set(category, body);
+    console.log(`${LOG_TAG} getMcpUrl ${category}: ${body.url}`);
+    return body.url;
+}
+// ============================================================================
+// HTTP 底层通信
+// ============================================================================
+/**
+ * 发送原始 HTTP 请求到 MCP Server（底层方法）
+ *
+ * 自动携带 Mcp-Session-Id 请求头（如果有），
+ * 并从响应头中更新 sessionId。
+ */
+async function sendRawJsonRpc(url, session, body) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), HTTP_REQUEST_TIMEOUT_MS);
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+    };
+    // Streamable HTTP：携带会话 ID
+    if (session.sessionId) {
+        headers["Mcp-Session-Id"] = session.sessionId;
+    }
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        if (err instanceof DOMException && err.name === "AbortError") {
+            throw new Error(`MCP 请求超时 (${HTTP_REQUEST_TIMEOUT_MS}ms)`);
+        }
+        throw new Error(`MCP 网络请求失败: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+    // 从响应头提取新的 sessionId（不直接修改入参，由调用方决定如何更新）
+    const newSessionId = response.headers.get("mcp-session-id");
+    if (!response.ok) {
+        throw new McpHttpError(response.status, `MCP HTTP 请求失败: ${response.status} ${response.statusText}`);
+    }
+    // Streamable HTTP：notification 响应可能无响应体（204 或 content-length: 0）
+    const contentLength = response.headers.get("content-length");
+    if (response.status === 204 || contentLength === "0") {
+        return { response, rpcResult: undefined, newSessionId };
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    // 处理 SSE 流式响应
+    if (contentType.includes("text/event-stream")) {
+        return { response, rpcResult: await parseSseResponse(response), newSessionId };
+    }
+    // 普通 JSON 响应 — 先读取文本，防止空内容导致 JSON.parse 报错
+    const text = await response.text();
+    if (!text.trim()) {
+        return { response, rpcResult: undefined, newSessionId };
+    }
+    const rpc = JSON.parse(text);
+    if (rpc.error) {
+        throw new McpRpcError(rpc.error.code, `MCP 调用错误 [${rpc.error.code}]: ${rpc.error.message}`, rpc.error.data);
+    }
+    return { response, rpcResult: rpc.result, newSessionId };
+}
+// ============================================================================
+// Session 管理
+// ============================================================================
+/**
+ * 对指定 URL 执行 Streamable HTTP 的 initialize 握手
+ *
+ * 发送 initialize → 接收 serverInfo → 发送 initialized 通知。
+ * 如果服务端未返回 Mcp-Session-Id，则标记为无状态模式，后续请求跳过 session 管理。
+ */
+async function initializeSession(url, category) {
+    const session = { sessionId: null, initialized: false, stateless: false };
+    console.log(`${LOG_TAG} 开始 initialize 握手 (category="${category}")`);
+    // 1. 发送 initialize 请求
+    const initBody = {
+        jsonrpc: "2.0",
+        id: aibotNodeSdk.generateReqId("mcp_init"),
+        method: "initialize",
+        params: {
+            protocolVersion: "2025-03-26",
+            capabilities: {},
+            clientInfo: { name: "wecom_mcp", version: "1.0.0" },
+        },
+    };
+    const { newSessionId: initSessionId } = await sendRawJsonRpc(url, session, initBody);
+    // 用返回的 newSessionId 更新 session（不再依赖副作用修改）
+    if (initSessionId) {
+        session.sessionId = initSessionId;
+    }
+    // 检查服务端是否返回了 Mcp-Session-Id
+    // 如果没有返回，说明该 Server 是无状态实现，无需维护 session
+    if (!session.sessionId) {
+        session.stateless = true;
+        session.initialized = true;
+        statelessCategories.add(category);
+        mcpSessionCache.set(category, session);
+        console.log(`${LOG_TAG} 无状态 Server 确认 (category="${category}")`);
+        return session;
+    }
+    // 2. 发送 initialized 通知（JSON-RPC notification 不带 id 字段）
+    const notifyBody = {
+        jsonrpc: "2.0",
+        method: "notifications/initialized",
+    };
+    // initialized 通知不需要等待响应，但 Streamable HTTP 要求通过 POST 发送
+    const { newSessionId: notifySessionId } = await sendRawJsonRpc(url, session, notifyBody);
+    // 如果 initialized 通知的响应也携带了 sessionId，以最新的为准
+    if (notifySessionId) {
+        session.sessionId = notifySessionId;
+    }
+    session.initialized = true;
+    mcpSessionCache.set(category, session);
+    console.log(`${LOG_TAG} 有状态 Session 建立成功 (category="${category}", sessionId="${session.sessionId}")`);
+    return session;
+}
+/**
+ * 获取或创建指定 URL 的 MCP 会话
+ *
+ * - 已确认无状态的 category：直接返回空 session，跳过握手
+ * - 已有可用有状态会话：直接返回缓存
+ * - 其他情况：执行 initialize 握手，并发请求会被合并
+ */
+async function getOrCreateSession(url, category) {
+    // 已确认为无状态的 Server，直接返回空 session 跳过握手
+    if (statelessCategories.has(category)) {
+        const cached = mcpSessionCache.get(category);
+        if (cached)
+            return cached;
+        // 首次发现被清除（理论上不会走到这里），重新走握手探测
+    }
+    const cached = mcpSessionCache.get(category);
+    if (cached?.initialized)
+        return cached;
+    // 防止并发重复初始化
+    const inflight = inflightInitRequests.get(category);
+    if (inflight)
+        return inflight;
+    const promise = initializeSession(url, category).finally(() => {
+        inflightInitRequests.delete(category);
+    });
+    inflightInitRequests.set(category, promise);
+    return promise;
+}
+// ============================================================================
+// SSE 解析
+// ============================================================================
+/**
+ * 解析 SSE 流式响应，提取最终的 JSON-RPC result
+ *
+ * 按照 SSE 规范，同一事件中的多个 `data:` 行会用换行符拼接。
+ * 空行分隔不同事件，取最后一个完整事件的数据。
+ */
+async function parseSseResponse(response) {
+    const text = await response.text();
+    const lines = text.split("\n");
+    // 按 SSE 规范解析：空行分隔事件，同一事件内的 data 行用换行拼接
+    let currentDataParts = [];
+    let lastEventData = "";
+    for (const line of lines) {
+        if (line.startsWith("data: ")) {
+            currentDataParts.push(line.slice(6));
+        }
+        else if (line.startsWith("data:")) {
+            // data: 后无空格时，值为空字符串
+            currentDataParts.push(line.slice(5));
+        }
+        else if (line.trim() === "" && currentDataParts.length > 0) {
+            // 空行表示事件结束，拼接所有 data 行
+            lastEventData = currentDataParts.join("\n").trim();
+            currentDataParts = [];
+        }
+    }
+    // 处理最后一个未以空行结尾的事件
+    if (currentDataParts.length > 0) {
+        lastEventData = currentDataParts.join("\n").trim();
+    }
+    if (!lastEventData) {
+        throw new Error("SSE 响应中未包含有效数据");
+    }
+    try {
+        const rpc = JSON.parse(lastEventData);
+        if (rpc.error) {
+            throw new McpRpcError(rpc.error.code, `MCP 调用错误 [${rpc.error.code}]: ${rpc.error.message}`, rpc.error.data);
+        }
+        return rpc.result;
+    }
+    catch (err) {
+        if (err instanceof SyntaxError) {
+            throw new Error(`SSE 响应解析失败: ${lastEventData.slice(0, 200)}`);
+        }
+        throw err;
+    }
+}
+// ============================================================================
+// 公共 API
+// ============================================================================
+/**
+ * 清理指定品类的所有 MCP 缓存（配置、会话、无状态标记）
+ *
+ * 当 MCP Server 返回特定错误码时调用，确保下次请求重新拉取配置并重建会话。
+ *
+ * @param category - MCP 品类名称
+ */
+function clearCategoryCache(category) {
+    console.log(`${LOG_TAG} 清理缓存 (category="${category}")`);
+    mcpConfigCache.delete(category);
+    mcpSessionCache.delete(category);
+    statelessCategories.delete(category);
+    inflightInitRequests.delete(category);
+}
+/**
+ * 发送 JSON-RPC 请求到 MCP Server（Streamable HTTP 协议）
+ *
+ * 自动管理 session 生命周期：
+ * - 无状态 Server：跳过 session 管理，直接发送请求
+ * - 有状态 Server：首次调用先执行 initialize 握手，session 失效（404）时自动重建并重试
+ *
+ * @param category - MCP 品类名称
+ * @param method - JSON-RPC 方法名
+ * @param params - JSON-RPC 参数
+ * @returns JSON-RPC result
+ */
+async function sendJsonRpc(category, method, params) {
+    const url = await getMcpUrl(category);
+    const body = {
+        jsonrpc: "2.0",
+        id: aibotNodeSdk.generateReqId("mcp_rpc"),
+        method,
+        ...(params !== undefined ? { params } : {}),
+    };
+    let session = await getOrCreateSession(url, category);
+    try {
+        const { rpcResult, newSessionId } = await sendRawJsonRpc(url, session, body);
+        // 用最新的 sessionId 更新 session
+        if (newSessionId) {
+            session.sessionId = newSessionId;
+        }
+        return rpcResult;
+    }
+    catch (err) {
+        // 特定 JSON-RPC 错误码触发缓存清理（统一在传输层处理，上层无需关心）
+        if (err instanceof McpRpcError && CACHE_CLEAR_ERROR_CODES.has(err.code)) {
+            clearCategoryCache(category);
+        }
+        // 无状态 Server 不存在 session 失效问题，直接抛出错误
+        if (session.stateless)
+            throw err;
+        // 有状态 Server：session 失效时服务端返回 404，需要重新初始化并重试一次
+        // 使用 McpHttpError.statusCode 精确匹配，避免字符串匹配 "404" 导致误判
+        if (err instanceof McpHttpError && err.statusCode === 404) {
+            console.log(`${LOG_TAG} Session 失效 (category="${category}")，开始重建...`);
+            mcpSessionCache.delete(category);
+            // 使用 rebuildSession 合并并发的 session 重建请求，避免竞态条件
+            session = await rebuildSession(url, category);
+            const { rpcResult, newSessionId } = await sendRawJsonRpc(url, session, body);
+            if (newSessionId) {
+                session.sessionId = newSessionId;
+            }
+            return rpcResult;
+        }
+        // 其他错误记录日志后抛出
+        console.error(`${LOG_TAG} RPC 请求失败 (category="${category}", method="${method}"): ${err instanceof Error ? err.message : String(err)}`);
+        throw err;
+    }
+}
+/**
+ * 合并并发的 session 重建请求
+ *
+ * 与 getOrCreateSession 类似，使用 inflightInitRequests 防止
+ * 多个并发请求同时遇到 404 时重复执行 initialize 握手。
+ */
+async function rebuildSession(url, category) {
+    const inflight = inflightInitRequests.get(category);
+    if (inflight)
+        return inflight;
+    const promise = initializeSession(url, category).finally(() => {
+        inflightInitRequests.delete(category);
+    });
+    inflightInitRequests.set(category, promise);
+    return promise;
+}
+
+/**
+ * MCP Schema 清洗模块
+ *
+ * 负责内联 $ref/$defs 引用并移除 Gemini 不支持的 JSON Schema 关键词，
+ * 防止 Gemini 模型解析 function response 时报 400 错误。
+ */
+/** Gemini 不支持的 JSON Schema 关键词 */
+const GEMINI_UNSUPPORTED_KEYWORDS = new Set([
+    "patternProperties", "additionalProperties", "$schema", "$id", "$ref", "$defs",
+    "definitions", "examples", "minLength", "maxLength", "minimum", "maximum",
+    "multipleOf", "pattern", "format", "minItems", "maxItems", "uniqueItems",
+    "minProperties", "maxProperties",
+]);
+/**
+ * 清洗 JSON Schema，内联 $ref 引用并移除 Gemini 不支持的关键词，
+ * 防止 Gemini 模型解析 function response 时报 400 错误。
+ */
+function cleanSchemaForGemini(schema) {
+    if (!schema || typeof schema !== "object")
+        return schema;
+    if (Array.isArray(schema))
+        return schema.map(cleanSchemaForGemini);
+    const obj = schema;
+    // 收集 $defs/definitions 用于后续 $ref 内联解析
+    const defs = {
+        ...(obj.$defs && typeof obj.$defs === "object" ? obj.$defs : {}),
+        ...(obj.definitions && typeof obj.definitions === "object" ? obj.definitions : {}),
+    };
+    return cleanWithDefs(obj, defs, new Set());
+}
+function cleanWithDefs(schema, defs, refStack) {
+    if (!schema || typeof schema !== "object")
+        return schema;
+    if (Array.isArray(schema))
+        return schema.map((item) => cleanWithDefs(item, defs, refStack));
+    const obj = schema;
+    // 合并当前层级的 $defs/definitions 到 defs 中
+    if (obj.$defs && typeof obj.$defs === "object") {
+        Object.assign(defs, obj.$defs);
+    }
+    if (obj.definitions && typeof obj.definitions === "object") {
+        Object.assign(defs, obj.definitions);
+    }
+    // 处理 $ref 引用：尝试内联解析
+    if (typeof obj.$ref === "string") {
+        const ref = obj.$ref;
+        if (refStack.has(ref))
+            return {}; // 防止循环引用
+        const match = ref.match(/^#\/(?:\$defs|definitions)\/(.+)$/);
+        if (match && match[1] && defs[match[1]]) {
+            const nextStack = new Set(refStack);
+            nextStack.add(ref);
+            return cleanWithDefs(defs[match[1]], defs, nextStack);
+        }
+        return {}; // 无法解析的 $ref，返回空对象
+    }
+    const cleaned = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (GEMINI_UNSUPPORTED_KEYWORDS.has(key))
+            continue;
+        if (key === "const") {
+            cleaned.enum = [value];
+            continue;
+        }
+        if (key === "properties" && value && typeof value === "object" && !Array.isArray(value)) {
+            cleaned[key] = Object.fromEntries(Object.entries(value).map(([k, v]) => [
+                k, cleanWithDefs(v, defs, refStack),
+            ]));
+        }
+        else if (key === "items" && value) {
+            cleaned[key] = Array.isArray(value)
+                ? value.map((item) => cleanWithDefs(item, defs, refStack))
+                : cleanWithDefs(value, defs, refStack);
+        }
+        else if ((key === "anyOf" || key === "oneOf" || key === "allOf") && Array.isArray(value)) {
+            // 过滤掉 null 类型的变体
+            const nonNull = value.filter((v) => {
+                if (!v || typeof v !== "object")
+                    return true;
+                const r = v;
+                return r.type !== "null";
+            });
+            if (nonNull.length === 1) {
+                // 只剩一个变体时直接内联
+                const single = cleanWithDefs(nonNull[0], defs, refStack);
+                if (single && typeof single === "object" && !Array.isArray(single)) {
+                    Object.assign(cleaned, single);
+                }
+            }
+            else {
+                cleaned[key] = nonNull.map((v) => cleanWithDefs(v, defs, refStack));
+            }
+        }
+        else {
+            cleaned[key] = value;
+        }
+    }
+    return cleaned;
+}
+
+/**
+ * wecom_mcp — 模拟 MCP 调用的 Agent Tool
+ *
+ * 通过 MCP Streamable HTTP 传输协议调用企业微信 MCP Server，
+ * 提供 list（列出所有工具）和 call（调用工具）两个操作。
+ *
+ * 在 skills 中的使用方式：
+ *   wecom_mcp list <category>
+ *   wecom_mcp call <category> <method> '<jsonArgs>'
+ *
+ * 示例：
+ *   wecom_mcp list contact
+ *   wecom_mcp call contact getContact '{}'
+ */
+// ============================================================================
+// 响应构造辅助
+// ============================================================================
+/** 构造统一的文本响应结构 */
+const textResult = (data) => ({
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+});
+/** 构造错误响应 */
+const errorResult = (err) => {
+    // 适配企业微信 API 返回的 { errcode, errmsg } 结构
+    if (err && typeof err === "object" && "errcode" in err) {
+        const { errcode, errmsg } = err;
+        return textResult({ error: errmsg ?? `错误码: ${errcode}`, errcode });
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return textResult({ error: message });
+};
+// ============================================================================
+// list 操作：列出某品类的所有 MCP 工具
+// ============================================================================
+const handleList = async (category) => {
+    const result = await sendJsonRpc(category, "tools/list");
+    const tools = result?.tools ?? [];
+    if (tools.length === 0) {
+        return { message: `品类 "${category}" 下暂无可用工具`, tools: [] };
+    }
+    return {
+        category,
+        count: tools.length,
+        tools: tools.map((t) => ({
+            name: t.name,
+            description: t.description ?? "",
+            // 清洗 inputSchema，内联 $ref/$defs 引用并移除 Gemini 不支持的关键词，
+            // 避免 Gemini 模型解析 function response 时报 400 错误
+            inputSchema: t.inputSchema ? cleanSchemaForGemini(t.inputSchema) : undefined,
+        })),
+    };
+};
+// ============================================================================
+// call 操作：调用某品类的某个 MCP 工具
+// ============================================================================
+/**
+ * 需要触发缓存清理的业务错误码集合
+ *
+ * 这些错误码出现在 MCP 工具调用返回的 content 文本中（业务层面），
+ * 与 JSON-RPC 层面的错误码不同，需要在此处额外检测。
+ *
+ * - 850002: 机器人未被授权使用对应能力，需清理缓存以便下次重新拉取配置
+ */
+const BIZ_CACHE_CLEAR_ERROR_CODES = new Set([850002]);
+/**
+ * 检查 tools/call 的返回结果中是否包含需要清理缓存的业务错误码
+ *
+ * MCP Server 可能在正常的 JSON-RPC 响应中返回业务层错误，
+ * 这些错误被包裹在 result.content[].text 中，需要解析后判断。
+ */
+const checkBizErrorAndClearCache = (result, category) => {
+    if (!result || typeof result !== "object")
+        return;
+    const { content } = result;
+    if (!Array.isArray(content))
+        return;
+    for (const item of content) {
+        if (item.type !== "text" || !item.text)
+            continue;
+        try {
+            const parsed = JSON.parse(item.text);
+            if (typeof parsed.errcode === "number" && BIZ_CACHE_CLEAR_ERROR_CODES.has(parsed.errcode)) {
+                console.log(`[mcp] 检测到业务错误码 ${parsed.errcode} (category="${category}")，清理缓存`);
+                clearCategoryCache(category);
+                return;
+            }
+        }
+        catch {
+            // text 不是 JSON 格式，跳过
+        }
+    }
+};
+const handleCall = async (category, method, args) => {
+    const result = await sendJsonRpc(category, "tools/call", {
+        name: method,
+        arguments: args,
+    });
+    // 检查业务层错误码，必要时清理缓存
+    checkBizErrorAndClearCache(result, category);
+    return result;
+};
+// ============================================================================
+// 参数解析
+// ============================================================================
+/**
+ * 解析 args 参数：支持 JSON 字符串或直接的对象
+ */
+const parseArgs = (args) => {
+    if (!args)
+        return {};
+    if (typeof args === "object")
+        return args;
+    try {
+        return JSON.parse(args);
+    }
+    catch (err) {
+        const detail = err instanceof SyntaxError ? err.message : String(err);
+        throw new Error(`args 参数不是合法的 JSON: ${args} (${detail})`);
+    }
+};
+// ============================================================================
+// 工具定义 & 导出
+// ============================================================================
+/**
+ * 创建 wecom_mcp Agent Tool 定义
+ */
+function createWeComMcpTool() {
+    return {
+        name: "wecom_mcp",
+        label: "企业微信 MCP 工具",
+        description: [
+            "通过 HTTP 直接调用企业微信 MCP Server。",
+            "支持两种操作：",
+            "  - list: 列出指定品类的所有 MCP 工具",
+            "  - call: 调用指定品类的某个 MCP 工具",
+            "",
+            "使用方式：",
+            "  wecom_mcp list <category>",
+            "  wecom_mcp call <category> <method> '<jsonArgs>'",
+            "",
+            "示例：",
+            "  列出 contact 品类所有工具：wecom_mcp list contact",
+            "  调用 contact 的 getContact：wecom_mcp call contact getContact '{}'",
+        ].join("\n"),
+        parameters: {
+            type: "object",
+            properties: {
+                action: {
+                    type: "string",
+                    enum: ["list", "call"],
+                    description: "操作类型：list（列出工具）或 call（调用工具）",
+                },
+                category: {
+                    type: "string",
+                    description: "MCP 品类名称，如 doc、contact 等，对应 mcpConfig 中的 key",
+                },
+                method: {
+                    type: "string",
+                    description: "要调用的 MCP 方法名（action=call 时必填）",
+                },
+                args: {
+                    type: ["string", "object"],
+                    description: "调用 MCP 方法的参数，可以是 JSON 字符串或对象（action=call 时使用，默认 {}）",
+                },
+            },
+            required: ["action", "category"],
+        },
+        async execute(_toolCallId, params) {
+            const p = params;
+            try {
+                switch (p.action) {
+                    case "list":
+                        return textResult(await handleList(p.category));
+                    case "call": {
+                        if (!p.method) {
+                            return textResult({ error: "action 为 call 时必须提供 method 参数" });
+                        }
+                        const args = parseArgs(p.args);
+                        return textResult(await handleCall(p.category, p.method, args));
+                    }
+                    default:
+                        return textResult({ error: `未知操作类型: ${String(p.action)}，支持 list 和 call` });
+                }
+            }
+            catch (err) {
+                return errorResult(err);
+            }
+        },
+    };
+}
+
+console.log(`[wecom] v${PLUGIN_VERSION} loaded`);
 const plugin = {
     id: "wecom-openclaw-plugin",
     name: "企业微信",
@@ -2783,6 +3350,13 @@ const plugin = {
     register(api) {
         setWeComRuntime(api.runtime);
         api.registerChannel({ plugin: wecomPlugin });
+        // 注册 wecom_mcp：通过 HTTP 直接调用企业微信 MCP Server
+        api.registerTool(createWeComMcpTool(), { name: "wecom_mcp" });
+        // ── Gateway 启动时自动确保 tools.alsoAllow 包含 wecom_mcp ──────────
+        // 在 gateway_start 阶段检测并写入，保证插件安装/更新后首次启动即生效
+        // api.on("gateway_start", async () => {
+        //   await ensureToolsAlsoAllow(api);
+        // });
         // 注入媒体发送指令和文件大小限制提示词
         api.on("before_prompt_build", () => {
             return {