@wecom/wecom-openclaw-plugin 2026.4.27 → 2026.4.28-beta.0

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

@@ -28,6 +28,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 +229,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) {

package/dist/src/state-manager.js

@@ -7,6 +7,34 @@
 import { createPersistentReqIdStore } from "./reqid-store.js";
 import { MESSAGE_STATE_TTL_MS, MESSAGE_STATE_CLEANUP_INTERVAL_MS, MESSAGE_STATE_MAX_SIZE, GLOBAL_WS_CLIENT_KEY, } from "./const.js";
 // ============================================================================
+// 全局单例状态（通过 globalThis + Symbol.for 确保跨 jiti loader 实例共享）
+//
+// 问题背景：openclaw 框架在不同阶段（主加载、configSchema 加载等）会创建
+// 多个独立的 jiti loader 实例，每个实例有独立的模块缓存（parentCache），
+// 导致本模块被多次实例化，模块级变量不共享。
+// 使用 globalThis + Symbol.for 可以确保同一进程内只有一份状态。
+// ============================================================================
+/** 全局共享状态的唯一键 */
+const SHARED_STATE_KEY = Symbol.for("wecom-openclaw-plugin:shared-state:v1");
+/**
+ * 获取或创建全局共享状态（进程内单例）
+ */
+function getSharedState() {
+    const existing = globalThis[SHARED_STATE_KEY];
+    if (existing)
+        return existing;
+    const state = {
+        wsClientInstances: new Map(),
+        messageStates: new Map(),
+        cleanupTimer: null,
+        reqIdStores: new Map(),
+    };
+    globalThis[SHARED_STATE_KEY] = state;
+    return state;
+}
+/** 进程内唯一的共享状态 */
+const shared = getSharedState();
+// ============================================================================
 // WSClient 实例管理
 // ============================================================================
 /** WSClient 实例管理 */
@@ -16,45 +44,45 @@ const wsClientInstances = (globalThis[GLOBAL_WS_CLIENT_KEY]
  * 获取指定账户的 WSClient 实例
  */
 export function getWeComWebSocket(accountId) {
-    return wsClientInstances.get(accountId) ?? null;
+    return shared.wsClientInstances.get(accountId) ?? null;
 }
 /**
  * 设置指定账户的 WSClient 实例
  */
 export function setWeComWebSocket(accountId, client) {
-    wsClientInstances.set(accountId, client);
+    shared.wsClientInstances.set(accountId, client);
 }
 /**
  * 删除指定账户的 WSClient 实例
  */
 export function deleteWeComWebSocket(accountId) {
-    wsClientInstances.delete(accountId);
+    shared.wsClientInstances.delete(accountId);
 }
-/** 消息状态管理 */
-const messageStates = new Map();
-/** 定期清理定时器 */
-let cleanupTimer = null;
+// ============================================================================
+// 消息状态管理（带 TTL 清理，防止内存泄漏）
+// ============================================================================
+// MessageStateEntry 接口已在上方 SharedState 定义处声明
 /**
  * 启动消息状态定期清理（自动 TTL 清理 + 容量限制）
  */
 export function startMessageStateCleanup() {
-    if (cleanupTimer)
+    if (shared.cleanupTimer)
         return;
-    cleanupTimer = setInterval(() => {
+    shared.cleanupTimer = setInterval(() => {
         pruneMessageStates();
     }, MESSAGE_STATE_CLEANUP_INTERVAL_MS);
     // 允许进程退出时不阻塞
-    if (cleanupTimer && typeof cleanupTimer === "object" && "unref" in cleanupTimer) {
-        cleanupTimer.unref();
+    if (shared.cleanupTimer && typeof shared.cleanupTimer === "object" && "unref" in shared.cleanupTimer) {
+        shared.cleanupTimer.unref();
     }
 }
 /**
  * 停止消息状态定期清理
  */
 export function stopMessageStateCleanup() {
-    if (cleanupTimer) {
-        clearInterval(cleanupTimer);
-        cleanupTimer = null;
+    if (shared.cleanupTimer) {
+        clearInterval(shared.cleanupTimer);
+        shared.cleanupTimer = null;
     }
 }
 /**
@@ -63,17 +91,17 @@ export function stopMessageStateCleanup() {
 function pruneMessageStates() {
     const now = Date.now();
     // 1. 清理过期条目
-    for (const [key, entry] of messageStates) {
+    for (const [key, entry] of shared.messageStates) {
         if (now - entry.createdAt >= MESSAGE_STATE_TTL_MS) {
-            messageStates.delete(key);
+            shared.messageStates.delete(key);
         }
     }
     // 2. 容量限制：如果仍超过最大条目数，按时间淘汰最旧的
-    if (messageStates.size > MESSAGE_STATE_MAX_SIZE) {
-        const sorted = [...messageStates.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
-        const toRemove = sorted.slice(0, messageStates.size - MESSAGE_STATE_MAX_SIZE);
+    if (shared.messageStates.size > MESSAGE_STATE_MAX_SIZE) {
+        const sorted = [...shared.messageStates.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+        const toRemove = sorted.slice(0, shared.messageStates.size - MESSAGE_STATE_MAX_SIZE);
         for (const [key] of toRemove) {
-            messageStates.delete(key);
+            shared.messageStates.delete(key);
         }
     }
 }
@@ -81,7 +109,7 @@ function pruneMessageStates() {
  * 设置消息状态
  */
 export function setMessageState(messageId, state) {
-    messageStates.set(messageId, {
+    shared.messageStates.set(messageId, {
         state,
         createdAt: Date.now(),
     });
@@ -90,12 +118,12 @@ export function setMessageState(messageId, state) {
  * 获取消息状态
  */
 export function getMessageState(messageId) {
-    const entry = messageStates.get(messageId);
+    const entry = shared.messageStates.get(messageId);
     if (!entry)
         return undefined;
     // 检查 TTL
     if (Date.now() - entry.createdAt >= MESSAGE_STATE_TTL_MS) {
-        messageStates.delete(messageId);
+        shared.messageStates.delete(messageId);
         return undefined;
     }
     return entry.state;
@@ -104,13 +132,13 @@ export function getMessageState(messageId) {
  * 删除消息状态
  */
 export function deleteMessageState(messageId) {
-    messageStates.delete(messageId);
+    shared.messageStates.delete(messageId);
 }
 /**
  * 清空所有消息状态
  */
 export function clearAllMessageStates() {
-    messageStates.clear();
+    shared.messageStates.clear();
 }
 // ============================================================================
 // ReqId 持久化存储管理（按 accountId 隔离）
@@ -120,12 +148,11 @@ export function clearAllMessageStates() {
  * 参考 createPersistentDedupe 模式：内存 + 磁盘双层、文件锁、原子写入、TTL 过期、防抖写入
  * 重启后可从磁盘恢复，确保主动推送消息时能获取到 reqId
  */
-const reqIdStores = new Map();
 function getOrCreateReqIdStore(accountId) {
-    let store = reqIdStores.get(accountId);
+    let store = shared.reqIdStores.get(accountId);
     if (!store) {
         store = createPersistentReqIdStore(accountId);
-        reqIdStores.set(accountId, store);
+        shared.reqIdStores.set(accountId, store);
     }
     return store;
 }
@@ -215,7 +242,7 @@ export function deleteSessionChatInfo(sessionKey) {
  */
 export async function cleanupAccount(accountId) {
     // 1. 断开 WSClient
-    const wsClient = wsClientInstances.get(accountId);
+    const wsClient = shared.wsClientInstances.get(accountId);
     if (wsClient) {
         try {
             wsClient.disconnect();
@@ -223,7 +250,7 @@ export async function cleanupAccount(accountId) {
         catch {
             // 忽略断开连接时的错误
         }
-        wsClientInstances.delete(accountId);
+        shared.wsClientInstances.delete(accountId);
     }
     // 2. 由于移除了磁盘存储，不再需要 flush reqId 存储
     // 注意：不删除 store，因为重连后可能还需要
@@ -235,7 +262,7 @@ export async function cleanupAll() {
     // 停止定期清理
     stopMessageStateCleanup();
     // 清理所有 WSClient
-    for (const [accountId, wsClient] of wsClientInstances) {
+    for (const [accountId, wsClient] of shared.wsClientInstances) {
         try {
             wsClient.disconnect();
         }
@@ -243,7 +270,7 @@ export async function cleanupAll() {
             // 忽略
         }
     }
-    wsClientInstances.clear();
+    shared.wsClientInstances.clear();
     // 由于移除了磁盘存储，不再需要 flush 所有 reqId 存储
     // 清空消息状态
     clearAllMessageStates();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wecom/wecom-openclaw-plugin",
-  "version": "2026.4.27",
+  "version": "2026.4.28-beta.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/wecom-smartsheet-data/SKILL.md

@@ -41,16 +41,23 @@ description: 企业微信智能表格数据（记录）管理技能。提供智
 
 添加一行或多行记录，单次建议 500 行内。
 
-**调用前**必须先了解目标表的字段类型（通过 `smartsheet_get_fields`）。
+**调用前**必须先了解目标表的字段类型（通过 `smartsheet_get_fields`），并查看[单元格值格式参考](references/cell-value-formats.md)，了解做法后再实施。
 
 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_add_records '{"docid": "DOCID", "sheet_id": "SHEETID", "records": [{"values": {"任务名称": [{"type": "text", "text": "完成需求文档"}], "优先级": [{"text": "高"}]}}]}'`
 
 各字段类型的值格式参见 [单元格值格式参考](references/cell-value-formats.md)。
 
+> ⚠️ **图片（IMAGE）/ 文件（ATTACHMENT）字段**：**必须且只能**直接在 cell value 中传入本地路径（`image_path` / `file_path`），格式见下方示例。**严禁**调用 `upload_doc_image`、`upload_doc_file` 或任何上传接口，**严禁**进行 base64 编码——无论文件大小、无论 API 返回何种错误，均不得绕过此规则。若 `image_path` / `file_path` 方式返回错误，应直接将错误码和错误信息告知用户，**不得**尝试其他上传方式。
+>
+> 图片字段示例：`"封面": [{"image_path": "/path/to/img.png", "title": "图片标题"}]`
+> 文件字段示例：`"文件": [{"file_path": "/path/to/file.pdf"}]`
+
 > ⚠️ 若返回 `errcode: 851003` 或 `errmsg` 包含 `no authority`（通常是企业可见范围 > 10 人的规模限制），切换到 Webhook 兜底方案，详见 [webhook-fallback.md](references/webhook-fallback.md)。
 
 ### smartsheet_update_records
 
+**调用前**必须先了解目标表的字段类型（通过 `smartsheet_get_fields`），并查看[单元格值格式参考](references/cell-value-formats.md)，了解做法后再实施。
+
 更新一行或多行记录，单次建议在 500 行内。需提供 record_id（通过 `smartsheet_get_records` 获取）。支持通过 `key_type` 指定 values 的 key 使用字段标题或字段 ID：
 
 - `CELL_VALUE_KEY_TYPE_FIELD_TITLE`：key 为字段标题
@@ -60,6 +67,11 @@ description: 企业微信智能表格数据（记录）管理技能。提供智
 
 **注意**：创建时间、最后编辑时间、创建人、最后编辑人字段不可更新。
 
+> ⚠️ **图片（IMAGE）/ 文件（ATTACHMENT）字段**：**必须且只能**直接在 cell value 中传入本地路径（`image_path` / `file_path`），格式见下方示例。**严禁**调用 `upload_doc_image`、`upload_doc_file` 或任何上传接口，**严禁**进行 base64 编码——无论文件大小、无论 API 返回何种错误，均不得绕过此规则。若 `image_path` / `file_path` 方式返回错误，应直接将错误码和错误信息告知用户，**不得**尝试其他上传方式。
+>
+> 图片字段示例：`"封面": [{"image_path": "/path/to/img.png", "title": "图片标题"}]`
+> 文件字段示例：`"文件": [{"file_path": "/path/to/file.pdf"}]`
+
 > ⚠️ 若返回 `errcode: 851003` 或 `errmsg` 包含 `no authority`（通常是企业可见范围 > 10 人的规模限制），切换到 Webhook 兜底方案，详见 [webhook-fallback.md](references/webhook-fallback.md)。注意 Webhook 只能更新通过 Webhook 写入的记录，人工创建的记录无法更新。
 
 ### smartsheet_delete_records
@@ -73,7 +85,9 @@ description: 企业微信智能表格数据（记录）管理技能。提供智
 1. **读取数据** → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_get_records '{"docid":"DOCID","sheet_id":"SHEETID"}'`
 2. **写入数据** → 先 `smartsheet_get_fields` 了解列类型 → 若涉及成员（USER）字段，先通过 `wecom-contact-lookup` 的 `get_userlist` 查找人员 userid → `smartsheet_add_records` 写入
 3. **更新数据** → 先 `smartsheet_get_records` 获取 record_id → 若涉及成员（USER）字段，先通过 `wecom-contact-lookup` 的 `get_userlist` 查找人员 userid → `smartsheet_update_records` 更新
-4. **删除数据** → 先 `smartsheet_get_records` 确认 record_id → `smartsheet_delete_records` 删除
-5. **写入失败 fallback** → 第 2/3 步返回 `errcode: 851003` / `no authority`（通常是企业可见范围 > 10 人的规模限制）时 → 请用户临时提供目标表的 Webhook 地址 + schema 示例 JSON（不保存到本地）→ 按 [webhook-fallback.md](references/webhook-fallback.md) 构造请求体发送
+4. **写入失败 fallback** → 第 2/3 步返回 `errcode: 851003` / `no authority`（通常是企业可见范围 > 10 人的规模限制）时 → 请用户临时提供目标表的 Webhook 地址 + schema 示例 JSON（不保存到本地）→ 按 [webhook-fallback.md](references/webhook-fallback.md) 构造请求体发送
+5. 若涉及**图片（IMAGE）或文件（ATTACHMENT）**字段，**必须且只能**直接在 cell value 中传入本地路径（`image_path` / `file_path`）。**严禁**调用 `upload_doc_image`、`upload_doc_file` 或任何上传接口，**严禁**进行 base64 编码——无论文件大小、无论 API 返回何种错误，均不得绕过此规则。若返回错误，直接将错误码和错误信息告知用户，不得尝试其他上传方式。传入格式参考 [单元格值格式参考](references/cell-value-formats.md)。
+6. **删除数据** → 先 `smartsheet_get_records` 确认 record_id → `smartsheet_delete_records` 删除
 
 > **注意**：成员（USER）类型字段需要填写 `user_id`，不能直接使用姓名。必须先通过 `wecom-contact-lookup` 技能的 `get_userlist` 接口按姓名查找到对应的 `userid` 后再使用。
+> **注意**：图片（IMAGE）或文件（ATTACHMENT）字段**必须且只能**直接在 cell value 中传入本地路径（`image_path` / `file_path`）。**严禁**调用 `upload_doc_image`、`upload_doc_file` 或任何上传接口，**严禁**进行 base64 编码——无论文件大小、无论 API 返回何种错误，均不得绕过此规则。若返回错误，直接将错误码和错误信息告知用户，不得尝试其他上传方式。格式参考 [单元格值格式参考](references/cell-value-formats.md)。

package/skills/wecom-smartsheet-data/references/cell-value-formats.md

@@ -118,12 +118,15 @@
 
 ### 9. 图片 (IMAGE)
 
-数组格式：
+数组格式，**必须且只能**直接在 cell value 中传入本地路径（`image_path`）。**严禁**调用 `upload_doc_image`、`upload_doc_file` 或任何上传接口，**严禁**进行 base64 编码——无论文件大小、无论 API 返回何种错误，均不得绕过此规则。若 `image_path` 方式返回错误，应直接将错误码和错误信息告知用户，**不得**尝试其他上传方式。
+
+#### 9.1. 图片本地路径传入（唯一合法方式）
 
 ```json
-"封面": [{"image_url": "https://example.com/img.png"}]
+"封面": [{"image_path": "/path/to/img.png", "title": "图片标题"}]
 ```
 
+
 ### 10. 地理位置 (LOCATION)
 
 数组格式：
@@ -132,6 +135,14 @@
 "地点": [{"source_type": 1, "id": "地点ID", "latitude": "39.9", "longitude": "116.3", "title": "北京"}]
 ```
 
+### 11. 文件（Attachment）
+
+数组格式，**必须且只能**直接在 cell value 中传入本地路径（`file_path`）。**严禁**调用 `upload_doc_image`、`upload_doc_file` 或任何上传接口，**严禁**进行 base64 编码——无论文件大小、无论 API 返回何种错误，均不得绕过此规则。若 `file_path` 方式返回错误，应直接将错误码和错误信息告知用户，**不得**尝试其他上传方式。
+
+```json
+"文件": [{"file_path": "/path/to/file.pdf"}]
+```
+
 ## 完整添加记录示例
 
 ```json

package/skills/wecom-smartsheet-schema/references/field-types.md

@@ -20,6 +20,7 @@
 | `FIELD_TYPE_CURRENCY` | 货币 | 货币金额 |
 | `FIELD_TYPE_PERCENTAGE` | 百分比 | 比率类数值（完成率、转化率） |
 | `FIELD_TYPE_BARCODE` | 条码 | 条形码/二维码 |
+| `FIELD_TYPE_ATTACHMENT` | 文件 | 文件/附件 |
 
 ## 添加字段示例