@wecom/wecom-openclaw-plugin 2026.4.2201 → 2026.5.7

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

@@ -13,6 +13,7 @@ import { docAuthErrorInterceptor } from "./doc-auth-error.js";
 import { mediaInterceptor } from "./msg-media.js";
 import { smartpageCreateInterceptor } from "./smartpage-create.js";
 import { smartpageExportInterceptor } from "./smartpage-export.js";
+import { smartsheetUploadInterceptor } from "./smartsheet-upload.js";
 // ============================================================================
 // 拦截器注册表（按注册顺序执行）
 // ============================================================================
@@ -22,6 +23,7 @@ const interceptors = [
     mediaInterceptor, // get_msg_media base64 拦截
     smartpageCreateInterceptor, // smartpage_create 本地文件读取
     smartpageExportInterceptor, // smartpage_get_export_result content → 本地文件
+    smartsheetUploadInterceptor, // smartsheet_add_records / update_records 本地文件上传
 ];
 /**
  * 收集匹配的 beforeCall 配置，合并后返回

package/dist/src/mcp/interceptors/smartsheet-upload.d.ts

@@ -0,0 +1,22 @@
+/**
+ * smartsheet_add_records / smartsheet_update_records 本地文件上传拦截器
+ *
+ * 核心逻辑：
+ * 大模型在调用 smartsheet_add_records / smartsheet_update_records 时，
+ * 可在 CellImageValue 中传入 image_path（本地图片路径）代替 image_url/title，
+ * 或在 CellAttachmentValue 中传入 file_path（本地文件路径）代替 file_id。
+ *
+ * 本拦截器在 beforeCall 阶段：
+ *   1. 深度扫描 records[].values 中的所有字段值，收集含 image_path / file_path 的单元格
+ *   2. 校验文件大小：单文件不超过 10MB，所有文件总计不超过 20MB
+ *   3. 并行读取本地文件 → base64 编码 → 调用 MCP 上传接口
+ *      - image_path → upload_doc_image → 获取 image_url
+ *      - file_path → upload_doc_file → 获取 file_id
+ *   4. 用上传结果替换原字段，移除 image_path / file_path
+ *   5. 返回修改后的完整 args
+ *
+ * 传给 MCP Server 的始终是标准协议格式（image_url / file_id），
+ * MCP Server 不需要感知 image_path / file_path 的存在。
+ */
+import type { CallInterceptor } from "./types.js";
+export declare const smartsheetUploadInterceptor: CallInterceptor;

package/dist/src/mcp/interceptors/smartsheet-upload.js

@@ -0,0 +1,263 @@
+/**
+ * smartsheet_add_records / smartsheet_update_records 本地文件上传拦截器
+ *
+ * 核心逻辑：
+ * 大模型在调用 smartsheet_add_records / smartsheet_update_records 时，
+ * 可在 CellImageValue 中传入 image_path（本地图片路径）代替 image_url/title，
+ * 或在 CellAttachmentValue 中传入 file_path（本地文件路径）代替 file_id。
+ *
+ * 本拦截器在 beforeCall 阶段：
+ *   1. 深度扫描 records[].values 中的所有字段值，收集含 image_path / file_path 的单元格
+ *   2. 校验文件大小：单文件不超过 10MB，所有文件总计不超过 20MB
+ *   3. 并行读取本地文件 → base64 编码 → 调用 MCP 上传接口
+ *      - image_path → upload_doc_image → 获取 image_url
+ *      - file_path → upload_doc_file → 获取 file_id
+ *   4. 用上传结果替换原字段，移除 image_path / file_path
+ *   5. 返回修改后的完整 args
+ *
+ * 传给 MCP Server 的始终是标准协议格式（image_url / file_id），
+ * MCP Server 不需要感知 image_path / file_path 的存在。
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { sendJsonRpc } from "../transport.js";
+// ============================================================================
+// 常量
+// ============================================================================
+/** 单个文件大小上限：10MB */
+const MAX_SINGLE_FILE_SIZE = 10 * 1024 * 1024;
+/** 所有文件总大小上限：20MB */
+const MAX_TOTAL_FILE_SIZE = 20 * 1024 * 1024;
+/** 上传请求超时时间（毫秒）：单次上传最大 10MB base64，给足时间 */
+const UPLOAD_TIMEOUT_MS = 60_000;
+/** beforeCall 整体超时延长到 120s（可能有多个文件并行上传） */
+const INTERCEPTOR_TIMEOUT_MS = 120_000;
+/** 日志前缀 */
+const LOG_TAG = "[mcp] smartsheet-upload:";
+// ============================================================================
+// 内部辅助函数
+// ============================================================================
+/**
+ * 深度扫描 records 中所有含 image_path / file_path 的单元格值对象，
+ * 返回待上传任务列表。
+ *
+ * records 结构：
+ *   [{ values: { "字段A": [{ image_path: "..." }], "字段B": [{ file_path: "..." }] } }]
+ *
+ * 字段值可能是数组（图片/附件/文本等）或标量（数字/布尔等），
+ * 仅对数组中的对象元素进行扫描。
+ */
+function collectUploadTasks(records) {
+    const tasks = [];
+    for (const record of records) {
+        const values = record.values;
+        if (!values || typeof values !== "object")
+            continue;
+        for (const fieldKey of Object.keys(values)) {
+            const fieldValue = values[fieldKey];
+            if (!Array.isArray(fieldValue))
+                continue;
+            for (const cellValue of fieldValue) {
+                if (!cellValue || typeof cellValue !== "object")
+                    continue;
+                const cell = cellValue;
+                if (typeof cell.image_path === "string" && cell.image_path) {
+                    tasks.push({
+                        kind: "image",
+                        filePath: cell.image_path,
+                        title: typeof cell.title === "string" ? cell.title : undefined,
+                        cellValue: cell,
+                    });
+                }
+                else if (typeof cell.file_path === "string" && cell.file_path) {
+                    tasks.push({
+                        kind: "file",
+                        filePath: cell.file_path,
+                        cellValue: cell,
+                    });
+                }
+            }
+        }
+    }
+    return tasks;
+}
+/**
+ * 校验所有待上传文件的大小
+ *
+ * - 单文件 > 10MB → 报错
+ * - 所有文件累计 > 20MB → 报错
+ */
+async function validateFileSizes(tasks) {
+    let totalSize = 0;
+    for (let i = 0; i < tasks.length; i++) {
+        const task = tasks[i];
+        let stat;
+        try {
+            stat = await fs.stat(task.filePath);
+        }
+        catch (err) {
+            throw new Error(`${LOG_TAG} 无法访问文件 "${task.filePath}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!stat.isFile()) {
+            throw new Error(`${LOG_TAG} "${task.filePath}" 不是一个文件`);
+        }
+        if (stat.size > MAX_SINGLE_FILE_SIZE) {
+            throw new Error(`${LOG_TAG} 文件 "${task.filePath}" 大小 ${(stat.size / 1024 / 1024).toFixed(1)}MB 超过单文件上限 10MB`);
+        }
+        totalSize += stat.size;
+        if (totalSize > MAX_TOTAL_FILE_SIZE) {
+            throw new Error(`${LOG_TAG} 累计文件大小 ${(totalSize / 1024 / 1024).toFixed(1)}MB 超过总上限 20MB（在文件 "${task.filePath}" 处超出）`);
+        }
+    }
+    if (totalSize > 0) {
+        console.log(`${LOG_TAG} 文件大小校验通过，共 ${tasks.length} 个文件，总计 ${(totalSize / 1024 / 1024).toFixed(2)}MB`);
+    }
+}
+/**
+ * 执行单个图片上传任务
+ *
+ * 读取本地文件 → base64 → 调用 upload_doc_image → 替换 cellValue
+ */
+async function executeImageUpload(task, docLocator) {
+    const buffer = await fs.readFile(task.filePath);
+    const base64Content = buffer.toString("base64");
+    const fileName = path.basename(task.filePath);
+    console.log(`${LOG_TAG} 上传图片: "${task.filePath}" (${(buffer.length / 1024).toFixed(0)}KB)`);
+    const result = await sendJsonRpc("doc", "tools/call", {
+        name: "upload_doc_image",
+        arguments: {
+            ...docLocator,
+            base64_content: base64Content,
+        },
+    }, { timeoutMs: UPLOAD_TIMEOUT_MS });
+    // 从 MCP result 中提取业务响应
+    const bizData = extractBizData(result, "upload_doc_image");
+    const imageUrl = bizData.url;
+    if (!imageUrl) {
+        throw new Error(`${LOG_TAG} upload_doc_image 未返回 url，文件: "${task.filePath}"`);
+    }
+    // 替换 cellValue：设置 image_url + title，移除 image_path
+    task.cellValue.image_url = imageUrl;
+    task.cellValue.title = task.title || fileName;
+    delete task.cellValue.image_path;
+    console.log(`${LOG_TAG} 图片上传成功: "${task.filePath}" → image_url="${imageUrl}"`);
+}
+/**
+ * 执行单个文件上传任务
+ *
+ * 读取本地文件 → base64 → 调用 upload_doc_file → 替换 cellValue
+ */
+async function executeFileUpload(task) {
+    const buffer = await fs.readFile(task.filePath);
+    const base64Content = buffer.toString("base64");
+    const fileName = path.basename(task.filePath);
+    console.log(`${LOG_TAG} 上传文件: "${task.filePath}" (${(buffer.length / 1024).toFixed(0)}KB)`);
+    const result = await sendJsonRpc("doc", "tools/call", {
+        name: "upload_doc_file",
+        arguments: {
+            file_name: fileName,
+            file_base64_content: base64Content,
+        },
+    }, { timeoutMs: UPLOAD_TIMEOUT_MS });
+    // 从 MCP result 中提取业务响应
+    const bizData = extractBizData(result, "upload_doc_file");
+    const fileId = bizData.fileid;
+    if (!fileId) {
+        throw new Error(`${LOG_TAG} upload_doc_file 未返回 fileid，文件: "${task.filePath}"`);
+    }
+    // 替换 cellValue：设置 file_id，移除 file_path
+    task.cellValue.file_id = fileId;
+    delete task.cellValue.file_path;
+    console.log(`${LOG_TAG} 文件上传成功: "${task.filePath}" → file_id="${fileId}"`);
+}
+/**
+ * 从 MCP tools/call 返回结构中提取业务 JSON 数据
+ *
+ * MCP result 格式：{ content: [{ type: "text", text: "{...json...}" }] }
+ */
+function extractBizData(result, interfaceName) {
+    const content = result?.content;
+    if (!Array.isArray(content)) {
+        throw new Error(`${LOG_TAG} ${interfaceName} 响应格式异常：缺少 content 数组`);
+    }
+    const textItem = content.find((c) => c.type === "text" && typeof c.text === "string");
+    if (!textItem) {
+        throw new Error(`${LOG_TAG} ${interfaceName} 响应格式异常：content 中无 text 类型条目`);
+    }
+    let bizData;
+    try {
+        bizData = JSON.parse(textItem.text);
+    }
+    catch {
+        throw new Error(`${LOG_TAG} ${interfaceName} 响应非 JSON: ${textItem.text.slice(0, 200)}`);
+    }
+    if (bizData.errcode !== 0) {
+        throw new Error(`${LOG_TAG} ${interfaceName} 业务错误: errcode=${bizData.errcode}, errmsg=${bizData.errmsg ?? "unknown"}`);
+    }
+    return bizData;
+}
+/**
+ * 从 args 中提取文档定位参数（docid 或 url），用于 upload_doc_image
+ */
+function extractDocLocator(args) {
+    if (typeof args.docid === "string" && args.docid) {
+        return { docid: args.docid };
+    }
+    if (typeof args.url === "string" && args.url) {
+        return { url: args.url };
+    }
+    throw new Error(`${LOG_TAG} args 中缺少 docid 或 url，无法调用 upload_doc_image`);
+}
+// ============================================================================
+// 拦截器实现
+// ============================================================================
+export const smartsheetUploadInterceptor = {
+    name: "smartsheet-upload",
+    /** 对 doc 品类的 smartsheet_add_records / smartsheet_update_records 生效 */
+    match: (ctx) => ctx.category === "doc" &&
+        (ctx.method === "smartsheet_add_records" || ctx.method === "smartsheet_update_records"),
+    /** 扫描 records 中的 image_path / file_path，上传后替换为 image_url / file_id */
+    beforeCall(ctx) {
+        const records = ctx.args.records;
+        if (!Array.isArray(records) || records.length === 0) {
+            return undefined;
+        }
+        // 收集所有待上传任务
+        const tasks = collectUploadTasks(records);
+        if (tasks.length === 0) {
+            return undefined;
+        }
+        console.log(`${LOG_TAG} 检测到 ${tasks.length} 个本地文件待上传`);
+        // 异步执行上传流程
+        return resolveUploads(ctx, tasks);
+    },
+};
+/**
+ * 执行文件校验和并行上传，返回替换后的 args
+ */
+async function resolveUploads(ctx, tasks) {
+    // 阶段 1：文件大小校验
+    await validateFileSizes(tasks);
+    // 提取文档定位参数（仅图片上传需要）
+    const hasImageTasks = tasks.some((t) => t.kind === "image");
+    let docLocator = {};
+    if (hasImageTasks) {
+        docLocator = extractDocLocator(ctx.args);
+    }
+    // 阶段 2：并行执行所有上传任务
+    // 上传完毕后 task.cellValue 已被原地修改（image_path/file_path 已替换为 image_url/file_id）
+    const uploadStart = performance.now();
+    await Promise.all(tasks.map((task) => {
+        if (task.kind === "image") {
+            return executeImageUpload(task, docLocator);
+        }
+        return executeFileUpload(task);
+    }));
+    const uploadMs = (performance.now() - uploadStart).toFixed(1);
+    console.log(`${LOG_TAG} 全部上传完成，共 ${tasks.length} 个文件，耗时 ${uploadMs}ms`);
+    // args 中的 records 已被原地修改，返回完整 args + 延长超时
+    return {
+        args: { ...ctx.args },
+        timeoutMs: INTERCEPTOR_TIMEOUT_MS,
+    };
+}

package/dist/src/mcp/transport.js

@@ -10,6 +10,7 @@
  * - MCP 配置运行时缓存（通过 WSClient 拉取 URL 并缓存在内存中）
  */
 import { generateReqId } from "@wecom/aibot-node-sdk";
+import { fetch as undiciFetch } from "undici";
 import { DEFAULT_ACCOUNT_ID } from "../openclaw-compat.js";
 import { getWeComWebSocket } from "../state-manager.js";
 import { MCP_GET_CONFIG_CMD, MCP_CONFIG_FETCH_TIMEOUT_MS } from "../const.js";
@@ -28,6 +29,26 @@ export const MEDIA_DOWNLOAD_TIMEOUT_MS = 120_000;
 const LOG_TAG = "[mcp]";
 /** 请求 MCP Server 时透传可信企业微信 userid 的 header 名 */
 export const WECOM_USERID_HEADER = "x-openclaw-wecom-userid";
+/**
+ * 构造 MCP 请求使用的 User-Agent
+ *
+ * 格式：`OpenClawPlugin/<version> <platform>/<arch>`
+ * 例如：`OpenClawPlugin/0.1.3 linux/x86_64`
+ *
+ * 说明：
+ * - version: 取自 package.json 的 PLUGIN_VERSION
+ * - platform: process.platform（linux / darwin / win32 ...）
+ * - arch: 将 Node 的 `x64` 归一化为传统 Unix 风格 `x86_64`，其他架构原样返回
+ */
+function buildUserAgent() {
+    const archMap = {
+        x64: "x86_64",
+        ia32: "i386",
+    };
+    const arch = archMap[process.arch] ?? process.arch;
+    return `OpenClawPlugin/${PLUGIN_VERSION} ${process.platform}/${arch}`;
+}
+const MCP_USER_AGENT = buildUserAgent();
 /**
  * MCP JSON-RPC 错误
  *
@@ -209,6 +230,7 @@ async function sendRawJsonRpc(url, session, body, timeoutMs = HTTP_REQUEST_TIMEO
     const headers = {
         "Content-Type": "application/json",
         Accept: "application/json, text/event-stream",
+        "User-Agent": MCP_USER_AGENT,
     };
     // Streamable HTTP：携带会话 ID
     if (session.sessionId) {
@@ -221,12 +243,14 @@ async function sendRawJsonRpc(url, session, body, timeoutMs = HTTP_REQUEST_TIMEO
     console.log(`${LOG_TAG} sendRawJsonRpc → ${body.method} | ${WECOM_USERID_HEADER}: ${headers[WECOM_USERID_HEADER] ?? "(not set)"}`);
     let response;
     try {
-        response = await fetch(url, {
+        // 使用 undici 提供的 fetch，规避 Node 18.0–18.17 原生 fetch 无法自定义 User-Agent 的 bug；
+        // undici 是项目已有依赖，且在所有支持的 Node 版本上行为一致。
+        response = (await undiciFetch(url, {
             method: "POST",
             headers,
             body: JSON.stringify(body),
             signal: controller.signal,
-        });
+        }));
     }
     catch (err) {
         if (err instanceof DOMException && err.name === "AbortError") {

package/dist/src/media-handler.d.ts

@@ -7,6 +7,24 @@ import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
 import type { RuntimeEnv } from "openclaw/plugin-sdk/runtime-env";
 import type { WSClient } from "@wecom/aibot-node-sdk";
 import type { ResolvedWeComAccount } from "./utils.js";
+/**
+ * 附件超过 OpenClaw 配置的 `agents.defaults.mediaMaxMb` 上限时抛出。
+ *
+ * 本错误由插件层主动判定并抛出，不依赖 OpenClaw 核心层错误消息的字符串匹配，
+ * 上层（monitor）可通过 `instanceof MediaOversizeError` 精确识别并向用户提示。
+ */
+export declare class MediaOversizeError extends Error {
+    readonly kind: "image" | "file";
+    readonly filename?: string;
+    readonly sizeBytes: number;
+    readonly maxBytes: number;
+    constructor(params: {
+        kind: "image" | "file";
+        filename?: string;
+        sizeBytes: number;
+        maxBytes: number;
+    });
+}
 /**
  * 下载并保存所有图片到本地，每张图片的下载带超时保护
  */

package/dist/src/media-handler.js

@@ -8,6 +8,30 @@ import { getWeComRuntime } from "./runtime.js";
 import { IMAGE_DOWNLOAD_TIMEOUT_MS, FILE_DOWNLOAD_TIMEOUT_MS, DEFAULT_MEDIA_MAX_MB } from "./const.js";
 import { withTimeout } from "./timeout.js";
 // ============================================================================
+// 媒体超限错误
+// ============================================================================
+/**
+ * 附件超过 OpenClaw 配置的 `agents.defaults.mediaMaxMb` 上限时抛出。
+ *
+ * 本错误由插件层主动判定并抛出，不依赖 OpenClaw 核心层错误消息的字符串匹配，
+ * 上层（monitor）可通过 `instanceof MediaOversizeError` 精确识别并向用户提示。
+ */
+export class MediaOversizeError extends Error {
+    kind;
+    filename;
+    sizeBytes;
+    maxBytes;
+    constructor(params) {
+        super(`Media oversize: kind=${params.kind}, size=${params.sizeBytes}, max=${params.maxBytes}` +
+            (params.filename ? `, filename=${params.filename}` : ""));
+        this.name = "MediaOversizeError";
+        this.kind = params.kind;
+        this.filename = params.filename;
+        this.sizeBytes = params.sizeBytes;
+        this.maxBytes = params.maxBytes;
+    }
+}
+// ============================================================================
 // 图片格式检测辅助函数（基于 file-type 包）
 // ============================================================================
 /**
@@ -66,11 +90,25 @@ export async function downloadAndSaveImages(params) {
                     runtime.log?.(`[wecom] WARN: Downloaded data is not a valid image format`);
                 }
             }
+            // 大小校验由插件层主动进行，超限抛出 MediaOversizeError，由 monitor 统一提示用户。
+            // 不再把 maxBytes 传给核心层 saveMediaBuffer，避免重复校验产生无结构化错误。
+            if (imageBuffer.length > maxBytes) {
+                throw new MediaOversizeError({
+                    kind: "image",
+                    filename: originalFilename,
+                    sizeBytes: imageBuffer.length,
+                    maxBytes,
+                });
+            }
             const saved = await core.channel.media.saveMediaBuffer(imageBuffer, imageContentType, "inbound", maxBytes, originalFilename);
             mediaList.push({ path: saved.path, contentType: saved.contentType });
             runtime.log?.(`[wecom][plugin] Image saved: path=${saved.path}, contentType=${saved.contentType}`);
         }
         catch (err) {
+            // 媒体超限错误需要上抛给 monitor，用于向用户发送明确的提示文案。
+            if (err instanceof MediaOversizeError) {
+                throw err;
+            }
             runtime.error?.(`[wecom] Failed to download image: ${String(err)}`);
         }
     }
@@ -110,11 +148,25 @@ export async function downloadAndSaveFiles(params) {
                 fileBuffer = fetched.buffer;
                 fileContentType = fetched.contentType ?? "application/octet-stream";
             }
+            // 大小校验由插件层主动进行，超限抛出 MediaOversizeError，由 monitor 统一提示用户。
+            // 不再把 maxBytes 传给核心层 saveMediaBuffer，避免重复校验产生无结构化错误。
+            if (fileBuffer.length > maxBytes) {
+                throw new MediaOversizeError({
+                    kind: "file",
+                    filename: originalFilename,
+                    sizeBytes: fileBuffer.length,
+                    maxBytes,
+                });
+            }
             const saved = await core.channel.media.saveMediaBuffer(fileBuffer, fileContentType, "inbound", maxBytes, originalFilename);
             mediaList.push({ path: saved.path, contentType: saved.contentType });
             runtime.log?.(`[wecom][plugin] File saved: path=${saved.path}, contentType=${saved.contentType}`);
         }
         catch (err) {
+            // 媒体超限错误需要上抛给 monitor，用于向用户发送明确的提示文案。
+            if (err instanceof MediaOversizeError) {
+                throw err;
+            }
             runtime.error?.(`[wecom] Failed to download file: ${String(err)}`);
         }
     }

package/dist/src/message-parser.d.ts

@@ -42,6 +42,10 @@ export interface MessageBody {
         url?: string;
         aeskey?: string;
     };
+    video?: {
+        url?: string;
+        aeskey?: string;
+    };
     quote?: {
         msgtype: string;
         text?: {
@@ -58,6 +62,10 @@ export interface MessageBody {
             url?: string;
             aeskey?: string;
         };
+        video?: {
+            url?: string;
+            aeskey?: string;
+        };
     };
     event?: {
         eventtype?: string;

package/dist/src/message-parser.js

@@ -175,6 +175,13 @@ export function parseMessageContent(body) {
                 fileAesKeys.set(body.file.url, body.file.aeskey);
             }
         }
+        // 处理视频消息（沿用 file 下载/解密通路，作为文件附件透传）
+        if (body.msgtype === "video" && body.video?.url) {
+            fileUrls.push(body.video.url);
+            if (body.video.aeskey) {
+                fileAesKeys.set(body.video.url, body.video.aeskey);
+            }
+        }
     }
     // 处理引用消息
     if (body.quote) {
@@ -198,6 +205,13 @@ export function parseMessageContent(body) {
                 fileAesKeys.set(body.quote.file.url, body.quote.file.aeskey);
             }
         }
+        else if (body.quote.msgtype === "video" && body.quote.video?.url) {
+            // 引用的视频消息：沿用文件下载通路
+            fileUrls.push(body.quote.video.url);
+            if (body.quote.video.aeskey) {
+                fileAesKeys.set(body.quote.video.url, body.quote.video.aeskey);
+            }
+        }
     }
     return { textParts, imageUrls, imageAesKeys, fileUrls, fileAesKeys, quoteContent };
 }