@wecom/wecom-openclaw-plugin 2026.3.30-beta.2 → 2026.3.31-beta.0

package/dist/src/mcp/interceptors/index.js

@@ -0,0 +1,66 @@
+/**
+ * MCP call 拦截器注册表与调度入口
+ *
+ * 所有 call 拦截器在此注册，按注册顺序执行。
+ * 新增拦截器只需：
+ *   1. 在 interceptors/ 目录下新建文件，实现 CallInterceptor 接口
+ *   2. 在下方 interceptors 数组中注册
+ *
+ * tool.ts 的 handleCall 无需任何改动。
+ */
+import { bizErrorInterceptor } from "./biz-error.js";
+import { mediaInterceptor } from "./msg-media.js";
+import { smartpageCreateInterceptor } from "./smartpage-create.js";
+import { smartpageExportInterceptor } from "./smartpage-export.js";
+// ============================================================================
+// 拦截器注册表（按注册顺序执行）
+// ============================================================================
+const interceptors = [
+    bizErrorInterceptor, // 业务错误码检查（所有 call 生效）
+    mediaInterceptor, // get_msg_media base64 拦截
+    smartpageCreateInterceptor, // smartpage_create 本地文件读取
+    smartpageExportInterceptor, // smartpage_get_export_result content → 本地文件
+];
+/**
+ * 收集匹配的 beforeCall 配置，合并后返回
+ *
+ * 合并策略：
+ * - timeoutMs: 取所有拦截器返回值中的最大值
+ * - args: 后注册的拦截器覆盖前者（一般同一调用只有一个拦截器会返回 args）
+ */
+export async function resolveBeforeCall(ctx) {
+    let mergedTimeoutMs;
+    let mergedArgs;
+    for (const interceptor of interceptors) {
+        if (!interceptor.match(ctx) || !interceptor.beforeCall)
+            continue;
+        const opts = await interceptor.beforeCall(ctx);
+        if (opts?.timeoutMs !== undefined) {
+            mergedTimeoutMs = mergedTimeoutMs === undefined
+                ? opts.timeoutMs
+                : Math.max(mergedTimeoutMs, opts.timeoutMs);
+        }
+        if (opts?.args !== undefined) {
+            mergedArgs = opts.args;
+        }
+    }
+    return {
+        options: mergedTimeoutMs !== undefined ? { timeoutMs: mergedTimeoutMs } : undefined,
+        args: mergedArgs,
+    };
+}
+/**
+ * 依次执行匹配的 afterCall 拦截器，管道式传递 result
+ *
+ * 前一个拦截器的返回值作为下一个拦截器的输入。
+ * 拦截器若不需要修改 result，应原样返回。
+ */
+export async function runAfterCall(ctx, result) {
+    let current = result;
+    for (const interceptor of interceptors) {
+        if (!interceptor.match(ctx) || !interceptor.afterCall)
+            continue;
+        current = await interceptor.afterCall(ctx, current);
+    }
+    return current;
+}

package/dist/src/mcp/interceptors/msg-media.js

@@ -0,0 +1,133 @@
+/**
+ * get_msg_media 响应拦截器
+ *
+ * 核心逻辑：
+ * 1. beforeCall: 设置延长的超时时间（120s），因为 base64 数据可达 ~27MB
+ * 2. afterCall: 从 MCP result 的 content[].text 中提取 base64_data，
+ *    解码为 Buffer 并通过 saveMediaBuffer 保存到本地媒体目录，
+ *    替换响应中的 base64_data 为 local_path，避免大模型被 base64 数据消耗 token
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { MEDIA_DOWNLOAD_TIMEOUT_MS } from "../transport.js";
+import { getWeComRuntime } from "../../runtime.js";
+import { detectMime } from "../../openclaw-compat.js";
+// ============================================================================
+// 拦截器实现
+// ============================================================================
+export const mediaInterceptor = {
+    name: "media",
+    /** 仅对 get_msg_media 方法生效 */
+    match: (ctx) => ctx.method === "get_msg_media",
+    /** 设置延长的超时时间 */
+    beforeCall() {
+        return { timeoutMs: MEDIA_DOWNLOAD_TIMEOUT_MS };
+    },
+    /** 拦截响应：base64 → 本地文件 */
+    async afterCall(ctx, result) {
+        return interceptMediaResponse(result);
+    },
+};
+// ============================================================================
+// 内部实现
+// ============================================================================
+/**
+ * 拦截 get_msg_media 的 MCP 响应
+ *
+ * 1. 从 MCP result 的 content[].text 中提取业务 JSON
+ * 2. 提取 media_item.base64_data，解码为 Buffer
+ * 3. 通过 openclaw SDK 的 saveMediaBuffer 保存到本地媒体目录
+ * 4. 替换响应：移除 base64_data，加入 local_path
+ *
+ * 这样大模型只看到轻量的文件路径信息，不会被 base64 数据消耗 token。
+ */
+async function interceptMediaResponse(result) {
+    const t0 = performance.now();
+    // 1. 提取 MCP result 中的 content 数组
+    const content = result?.content;
+    if (!Array.isArray(content))
+        return result;
+    const textItem = content.find((c) => c.type === "text" && typeof c.text === "string");
+    if (!textItem)
+        return result;
+    // 2. 解析业务 JSON
+    let bizData;
+    try {
+        bizData = JSON.parse(textItem.text);
+    }
+    catch {
+        // 非 JSON 格式，原样返回
+        return result;
+    }
+    // 3. 校验业务响应：errcode !== 0 或无 media_item 时原样返回
+    if (bizData.errcode !== 0)
+        return result;
+    const mediaItem = bizData.media_item;
+    if (!mediaItem || typeof mediaItem.base64_data !== "string")
+        return result;
+    const base64Data = mediaItem.base64_data;
+    const mediaName = mediaItem.name;
+    const mediaType = mediaItem.type;
+    const mediaId = mediaItem.media_id;
+    const tParsed = performance.now();
+    // 4. 解码 base64 → Buffer
+    const buffer = Buffer.from(base64Data, "base64");
+    const tDecoded = performance.now();
+    // 5. 检测 contentType，并通过 saveMediaBuffer 保存到本地媒体目录
+    const contentType = await detectMime({ buffer, filePath: mediaName }) ?? "application/octet-stream";
+    const tMimeDetected = performance.now();
+    // 企业微信聊天记录附件可达 20MB（文件消息上限），
+    // 而 saveMediaBuffer 默认 maxBytes 为 5MB（针对 outbound 场景），
+    // 此处显式放宽到 20MB 以支持大文件下载。
+    const INBOUND_MAX_BYTES = 20 * 1024 * 1024; // 20MB
+    const core = getWeComRuntime();
+    const saved = await core.channel.media.saveMediaBuffer(buffer, contentType, "inbound", INBOUND_MAX_BYTES, // maxBytes: 放宽到 20MB，匹配企业微信文件消息上限
+    mediaName);
+    // 5.1 补偿：核心库 EXT_BY_MIME 可能缺少某些格式映射（如 audio/amr），
+    //     导致保存的文件没有后缀。此处检测并修复。
+    const MIME_EXT_PATCH = {
+        "audio/amr": ".amr",
+    };
+    const patchExt = MIME_EXT_PATCH[contentType];
+    if (patchExt && !path.extname(saved.path)) {
+        const newPath = saved.path + patchExt;
+        try {
+            await fs.rename(saved.path, newPath);
+            saved.path = newPath;
+        }
+        catch {
+            // rename 失败不影响主流程，文件仍可用
+        }
+    }
+    const tSaved = performance.now();
+    // 6. 构造精简响应，移除 base64_data，加入本地路径
+    const newBizData = {
+        errcode: 0,
+        errmsg: "ok",
+        media_item: {
+            media_id: mediaId,
+            name: mediaName ?? saved.path.split("/").pop(),
+            type: mediaType,
+            local_path: saved.path,
+            size: buffer.length,
+            content_type: saved.contentType,
+        },
+    };
+    const tEnd = performance.now();
+    // 耗时日志：各环节耗时（ms）
+    console.log(`[mcp] get_msg_media 拦截成功: media_id=${mediaId ?? "unknown"}, ` +
+        `type=${mediaType ?? "unknown"}, size=${buffer.length}, saved=${saved.path}\n` +
+        `  ⏱ 耗时明细 (总 ${(tEnd - t0).toFixed(1)}ms):\n` +
+        `    解析响应 JSON:   ${(tParsed - t0).toFixed(1)}ms\n` +
+        `    base64 解码:     ${(tDecoded - tParsed).toFixed(1)}ms  (${(base64Data.length / 1024).toFixed(0)}KB base64 → ${(buffer.length / 1024).toFixed(0)}KB buffer)\n` +
+        `    MIME 检测:       ${(tMimeDetected - tDecoded).toFixed(1)}ms  (${contentType})\n` +
+        `    saveMediaBuffer: ${(tSaved - tMimeDetected).toFixed(1)}ms\n` +
+        `    构造响应:        ${(tEnd - tSaved).toFixed(1)}ms`);
+    // 7. 返回修改后的 MCP result 结构
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify(newBizData),
+            }],
+    };
+}

package/dist/src/mcp/interceptors/smartpage-create.js

@@ -0,0 +1,132 @@
+/**
+ * smartpage_create 请求拦截器
+ *
+ * 核心逻辑：
+ * smartpage_create 的 pages 数组中，每个 page 可能包含 page_filepath 字段
+ * （指向本地 markdown 文件），用于避免在命令行传递大段文本内容。
+ * 本拦截器在 beforeCall 阶段遍历 pages 数组，逐个读取 page_filepath
+ * 指向的本地文件内容，填入 page_content 字段，并移除 page_filepath。
+ *
+ * 入参约定：
+ *   wecom_mcp call doc smartpage_create '{
+ *     "title": "主页标题",
+ *     "pages": [
+ *       {"page_title": "页面1", "page_filepath": "/tmp/page1.md", "content_type": "markdown"},
+ *       {"page_title": "页面2", "page_filepath": "/tmp/page2.md", "content_type": "markdown"}
+ *     ]
+ *   }'
+ *
+ * 拦截器行为：
+ *   1. 检测 args.pages 数组
+ *   2. 校验文件大小：单文件不超过 10MB，所有文件总计不超过 20MB
+ *   3. 遍历每个 page，若存在 page_filepath 则读取本地文件内容
+ *   4. 将文件内容填入 page_content 字段，移除 page_filepath
+ *   5. 返回修改后的完整 args
+ *
+ * 传给 MCP Server 的格式：
+ *   { "title": "...", "pages": [{"page_title": "...", "page_content": "...", "content_type": "..."}] }
+ */
+import * as fs from "node:fs/promises";
+// ============================================================================
+// 常量
+// ============================================================================
+/** 单个 page_filepath 文件大小上限：10MB */
+const MAX_SINGLE_FILE_SIZE = 10 * 1024 * 1024;
+/** 所有 page_filepath 文件总大小上限：20MB */
+const MAX_TOTAL_FILE_SIZE = 20 * 1024 * 1024;
+// ============================================================================
+// 内部辅助函数
+// ============================================================================
+/**
+ * 校验所有 page_filepath 的文件大小
+ *
+ * 使用 fs.stat 在读取文件内容之前检查大小，避免超大文件被加载到内存。
+ * - 单文件 > 10MB → 报错
+ * - 所有文件累计 > 20MB → 报错
+ */
+async function validateFileSize(pages) {
+    let totalSize = 0;
+    for (let i = 0; i < pages.length; i++) {
+        const filePath = pages[i].page_filepath;
+        if (typeof filePath !== "string" || !filePath)
+            continue;
+        let stat;
+        try {
+            stat = await fs.stat(filePath);
+        }
+        catch (err) {
+            // stat 失败不在这里处理，留给后续 readFile 阶段抛出更详细的错误
+            continue;
+        }
+        if (stat.size > MAX_SINGLE_FILE_SIZE) {
+            console.error(`[mcp] smartpage_create: pages[${i}] 文件 "${filePath}" ` +
+                `大小 ${(stat.size / 1024 / 1024).toFixed(1)}MB 超过单文件上限 10MB`);
+            throw new Error("内容大小超出限制，无法创建");
+        }
+        totalSize += stat.size;
+        if (totalSize > MAX_TOTAL_FILE_SIZE) {
+            console.error(`[mcp] smartpage_create: 累计文件大小 ${(totalSize / 1024 / 1024).toFixed(1)}MB ` +
+                `超过总上限 20MB（在 pages[${i}] "${filePath}" 处超出）`);
+            throw new Error("内容大小超出限制，无法创建");
+        }
+    }
+    if (totalSize > 0) {
+        console.log(`[mcp] smartpage_create: 文件大小校验通过，总计 ${(totalSize / 1024 / 1024).toFixed(2)}MB`);
+    }
+}
+/** 异步解析 pages 中的 page_filepath，返回 BeforeCallOptions */
+async function resolvePages(ctx, pages) {
+    console.log(`[mcp] smartpage_create: 开始解析 ${pages.length} 个 page 的 page_filepath`);
+    // 阶段 1：文件大小校验（stat 阶段，不读内容）
+    await validateFileSize(pages);
+    // 阶段 2：读取文件内容
+    const resolvedPages = await Promise.all(pages.map(async (page, index) => {
+        const filePath = page.page_filepath;
+        if (typeof filePath !== "string" || !filePath) {
+            // 该 page 没有 page_filepath，保留原样（可能已有 page_content）
+            return page;
+        }
+        let fileContent;
+        try {
+            fileContent = await fs.readFile(filePath, "utf-8");
+        }
+        catch (err) {
+            throw new Error(`smartpage_create: pages[${index}] 无法读取文件 "${filePath}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+        console.log(`[mcp] smartpage_create: pages[${index}] 读取成功 "${filePath}" (${fileContent.length} chars)`);
+        // 构造新的 page 对象：填入 page_content，移除 page_filepath
+        const { page_filepath: _, ...rest } = page;
+        return { ...rest, page_content: fileContent };
+    }));
+    console.log(`[mcp] smartpage_create: 所有 page_filepath 解析完成`);
+    // 返回修改后的完整 args
+    return {
+        args: {
+            ...ctx.args,
+            pages: resolvedPages,
+        },
+    };
+}
+// ============================================================================
+// 拦截器实现
+// ============================================================================
+export const smartpageCreateInterceptor = {
+    name: "smartpage-create",
+    /** 仅对 doc 品类的 smartpage_create 方法生效 */
+    match: (ctx) => ctx.category === "doc" && ctx.method === "smartpage_create",
+    /** 遍历 pages 数组，逐个读取 page_filepath 填入 page_content */
+    beforeCall(ctx) {
+        const pages = ctx.args.pages;
+        if (!Array.isArray(pages) || pages.length === 0) {
+            // 没有 pages 数组，不做拦截
+            return undefined;
+        }
+        // 检查是否有任何 page 包含 page_filepath
+        const hasFilePath = pages.some((p) => typeof p.page_filepath === "string" && p.page_filepath);
+        if (!hasFilePath) {
+            // 所有 page 都没有 page_filepath（可能直接传了 page_content），不做拦截
+            return undefined;
+        }
+        return resolvePages(ctx, pages);
+    },
+};

package/dist/src/mcp/interceptors/smartpage-export.js

@@ -0,0 +1,87 @@
+/**
+ * smartpage_get_export_result 响应拦截器
+ *
+ * 核心逻辑：
+ * MCP Server 返回的 smartpage_get_export_result 响应中，当 task_done=true 时
+ * 会包含 content 字段（markdown 文本内容）。该内容可能很大，直接返回给 LLM
+ * 会消耗大量 token。
+ *
+ * 本拦截器在 afterCall 阶段：
+ * 1. 检测 task_done=true 且存在 content 字段
+ * 2. 将 content 保存到本地文件（使用与 msg-media 一致的媒体目录）
+ * 3. 用 content_path（文件路径）替换 content 字段
+ *
+ * 这样 LLM 只看到轻量的文件路径信息，Skill 可通过文件路径读取完整内容。
+ */
+import { getWeComRuntime } from "../../runtime.js";
+// ============================================================================
+// 拦截器实现
+// ============================================================================
+export const smartpageExportInterceptor = {
+    name: "smartpage-export",
+    /** 仅对 doc 品类的 smartpage_get_export_result 方法生效 */
+    match: (ctx) => ctx.category === "doc" && ctx.method === "smartpage_get_export_result",
+    /** 拦截响应：将 markdown content 保存为本地文件 */
+    async afterCall(_ctx, result) {
+        return interceptExportResponse(result);
+    },
+};
+// ============================================================================
+// 内部实现
+// ============================================================================
+/**
+ * 拦截 smartpage_get_export_result 的 MCP 响应
+ *
+ * 1. 从 MCP result 的 content[].text 中提取业务 JSON
+ * 2. 检测 task_done=true 且存在 content 字段
+ * 3. 将 content（markdown 文本）通过 saveMediaBuffer 保存到本地媒体目录
+ * 4. 构造新响应：移除 content，添加 content_path
+ */
+async function interceptExportResponse(result) {
+    // 1. 提取 MCP result 中的 content 数组
+    const content = result?.content;
+    if (!Array.isArray(content))
+        return result;
+    const textItem = content.find((c) => c.type === "text" && typeof c.text === "string");
+    if (!textItem)
+        return result;
+    // 2. 解析业务 JSON
+    let bizData;
+    try {
+        bizData = JSON.parse(textItem.text);
+    }
+    catch {
+        // 非 JSON 格式，原样返回
+        return result;
+    }
+    // 3. 校验：errcode !== 0 或 task_done 不为 true 或无 content 时原样返回
+    if (bizData.errcode !== 0)
+        return result;
+    if (bizData.task_done !== true)
+        return result;
+    if (typeof bizData.content !== "string")
+        return result;
+    const markdownContent = bizData.content;
+    console.log(`[mcp] smartpage_get_export_result: 拦截 content (${markdownContent.length} chars)，保存到本地文件`);
+    // 4. 将 markdown 内容通过 saveMediaBuffer 保存到本地媒体目录
+    //    使用 text/markdown 类型，与 msg-media 拦截器保持一致的路径管理
+    const buffer = Buffer.from(markdownContent, "utf-8");
+    const core = getWeComRuntime();
+    const saved = await core.channel.media.saveMediaBuffer(buffer, "text/markdown", "inbound", undefined, // maxBytes: markdown 文本通常不大，使用默认限制
+    "smartpage_export.md");
+    console.log(`[mcp] smartpage_get_export_result: 已保存到 ${saved.path}`);
+    // 5. 构造新响应：移除 content，添加 content_path
+    const newBizData = {
+        errcode: bizData.errcode,
+        errmsg: bizData.errmsg ?? "ok",
+        task_done: true,
+        content_path: saved.path,
+    };
+    // 6. 返回修改后的 MCP result 结构
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify(newBizData),
+            }],
+    };
+}

package/dist/src/mcp/interceptors/types.js

@@ -0,0 +1,7 @@
+/**
+ * MCP call 拦截器类型定义
+ *
+ * 拦截器用于在 tools/call 调用前后注入特殊逻辑，
+ * 如修改超时配置、变换响应结果等，避免在 tool.ts 中堆积 if/else。
+ */
+export {};

package/dist/src/mcp/schema.js

@@ -0,0 +1,99 @@
+/**
+ * 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 错误。
+ */
+export 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;
+}