@wecom/wecom-openclaw-plugin 2026.4.2201 → 2026.5.7-beta.0

package/dist/src/monitor.js

@@ -17,21 +17,31 @@
  */
 import * as os from "os";
 import * as path from "path";
-import { WSClient, generateReqId, WSAuthFailureError, WSReconnectExhaustedError } from "@wecom/aibot-node-sdk";
-import { getWeComRuntime } from "./runtime.js";
-import { getDefaultMediaLocalRoots, resolveStateDir } from "./openclaw-compat.js";
+import { WSClient, generateReqId, WSAuthFailureError, WSReconnectExhaustedError, } from "@wecom/aibot-node-sdk";
 import { CHANNEL_ID, THINKING_MESSAGE, MEDIA_IMAGE_PLACEHOLDER, MEDIA_DOCUMENT_PLACEHOLDER, WS_HEARTBEAT_INTERVAL_MS, WS_MAX_RECONNECT_ATTEMPTS, WS_MAX_AUTH_FAILURE_ATTEMPTS, EVENT_ENTER_CHECK_UPDATE, CMD_ENTER_EVENT_REPLY, SCENE_WECOM_OPENCLAW, } from "./const.js";
+import { checkDmPolicy } from "./dm-policy.js";
+import { processDynamicRouting } from "./dynamic-routing.js";
+import { checkGroupPolicy } from "./group-policy.js";
+import { downloadAndSaveImages, downloadAndSaveFiles, MediaOversizeError, } from "./media-handler.js";
+import { uploadAndSendMedia } from "./media-uploader.js";
 import { parseMessageContent } from "./message-parser.js";
 import { sendWeComReply, StreamExpiredError } from "./message-sender.js";
-import { downloadAndSaveImages, downloadAndSaveFiles } from "./media-handler.js";
-import { uploadAndSendMedia } from "./media-uploader.js";
-import { maskTemplateCardBlocks } from "./template-card-parser.js";
-import { updateTemplateCardOnEvent, processTemplateCardsIfNeeded, } from "./template-card-manager.js";
-import { checkGroupPolicy } from "./group-policy.js";
-import { checkDmPolicy } from "./dm-policy.js";
+import { getDefaultMediaLocalRoots, resolveStateDir } from "./openclaw-compat.js";
+import { getWeComRuntime } from "./runtime.js";
 import { setWeComWebSocket, setMessageState, deleteMessageState, setReqIdForChat, setSessionChatInfo, warmupReqIdStore, startMessageStateCleanup, stopMessageStateCleanup, cleanupAccount, } from "./state-manager.js";
+import { updateTemplateCardOnEvent, processTemplateCardsIfNeeded, } from "./template-card-manager.js";
+import { maskTemplateCardBlocks } from "./template-card-parser.js";
 import { PLUGIN_VERSION } from "./version.js";
-import { processDynamicRouting } from "./dynamic-routing.js";
+// ============================================================================
+// 附件超限提示文案
+// ============================================================================
+/**
+ * 构造「附件超过 OpenClaw 大小限制」的中文提示文案。
+ */
+function buildMediaOversizeHintText(err) {
+    const maxMb = err.maxBytes / 1024 / 1024;
+    return `当前OpenClaw限制文件不超过${maxMb}MB，请修改OpenClaw配置。`;
+}
 // ============================================================================
 // 媒体本地路径白名单扩展
 // ============================================================================
@@ -135,7 +145,12 @@ function buildMessageContext(frame, account, config, text, mediaList, quoteConte
     const fromLabel = chatType === "group" ? `group:${chatId}` : `user:${body.from.userid}`;
     // 当只有媒体没有文本时，使用占位符标识媒体类型
     const hasImages = mediaList.some((m) => m.contentType?.startsWith("image/"));
-    const messageBody = text || (mediaList.length > 0 ? (hasImages ? MEDIA_IMAGE_PLACEHOLDER : MEDIA_DOCUMENT_PLACEHOLDER) : "");
+    const messageBody = text ||
+        (mediaList.length > 0
+            ? hasImages
+                ? MEDIA_IMAGE_PLACEHOLDER
+                : MEDIA_DOCUMENT_PLACEHOLDER
+            : "");
     // 构建多媒体数组
     const mediaPaths = mediaList.length > 0 ? mediaList.map((m) => m.path) : undefined;
     const mediaTypes = mediaList.length > 0
@@ -272,7 +287,9 @@ async function finishThinkingStream(ctx) {
     }
     else if (state.hasMedia) {
         if (state.hasMediaFailed && state.mediaErrorSummary) {
-            finishText = finishText ? `${finishText}\n\n${state.mediaErrorSummary}` : state.mediaErrorSummary;
+            finishText = finishText
+                ? `${finishText}\n\n${state.mediaErrorSummary}`
+                : state.mediaErrorSummary;
         }
         else if (!finishText) {
             finishText = "📎 文件已发送，请查收。";
@@ -283,7 +300,14 @@ async function finishThinkingStream(ctx) {
         let expired = state.streamExpired;
         if (!expired) {
             try {
-                await sendWeComReply({ wsClient, frame, text: finishText, runtime, finish: true, streamId: state.streamId });
+                await sendWeComReply({
+                    wsClient,
+                    frame,
+                    text: finishText,
+                    runtime,
+                    finish: true,
+                    streamId: state.streamId,
+                });
             }
             catch (err) {
                 if (err instanceof StreamExpiredError) {
@@ -307,7 +331,7 @@ async function finishThinkingStream(ctx) {
  * 路由消息到核心处理流程并处理回复
  */
 async function routeAndDispatchMessage(params) {
-    const { ctxPayload, route, storePath, chatId, chatType, config, account, wsClient, frame, state, runtime, onCleanup } = params;
+    const { ctxPayload, route, storePath, chatId, chatType, config, account, wsClient, frame, state, runtime, onCleanup, } = params;
     const core = getWeComRuntime();
     const ctx = { wsClient, frame, state, account, runtime };
     // 防止 onCleanup 被多次调用（onError 回调与 catch 块可能重复触发）
@@ -341,17 +365,23 @@ async function routeAndDispatchMessage(params) {
             ctx: ctxPayload,
             cfg: config,
             replyOptions: {
-                // 打印 LLM 返回的原始分片内容（在 openclaw 核心对 MEDIA: 指令解析之前），
-                // 用于排查流式分片导致 MEDIA 指令被切断、识别丢失等问题
-                onPartialReply: (payload) => {
-                    runtime.log?.(`[openclaw -> plugin][partial] payload=${JSON.stringify(payload)}`);
-                },
+            // 打印 LLM 返回的原始分片内容（在 openclaw 核心对 MEDIA: 指令解析之前），
+            // 用于排查流式分片导致 MEDIA 指令被切断、识别丢失等问题
+            // onPartialReply: (payload: unknown) => {
+            // runtime.log?.(`[openclaw -> plugin][partial] payload=${JSON.stringify(payload)}`);
+            // },
             },
             dispatcherOptions: {
                 onReplyStart: async () => {
                     if (!isShowThink && state.streamId && !state.accumulatedText) {
                         try {
-                            await sendThinkingReply({ wsClient, frame, streamId: state.streamId, runtime, state });
+                            await sendThinkingReply({
+                                wsClient,
+                                frame,
+                                streamId: state.streamId,
+                                runtime,
+                                state,
+                            });
                         }
                         catch (e) {
                             runtime.error?.(`[wecom] sendThinkingReply threw err: ${String(e)}`);
@@ -363,10 +393,14 @@ async function routeAndDispatchMessage(params) {
                     runtime.log?.(`[openclaw -> plugin] kind=${info.kind}, payload=${JSON.stringify(payload)}, info=${JSON.stringify(info)}`);
                     // 累积文本
                     if (payload.text) {
-                        state.accumulatedText += `${payload.text || ''}`;
+                        state.accumulatedText += `${payload.text || ""}`;
                     }
                     // 发送媒体（统一走主动发送）
-                    const mediaUrls = payload.mediaUrls?.length ? payload.mediaUrls : payload.mediaUrl ? [payload.mediaUrl] : [];
+                    const mediaUrls = payload.mediaUrls?.length
+                        ? payload.mediaUrls
+                        : payload.mediaUrl
+                            ? [payload.mediaUrl]
+                            : [];
                     if (mediaUrls.length > 0) {
                         try {
                             await sendMediaBatch(ctx, mediaUrls);
@@ -392,7 +426,14 @@ async function routeAndDispatchMessage(params) {
                             // if (displayText !== state.accumulatedText) {
                             //   runtime.log?.(`[wecom][template-card] Mid-frame masked: original=${state.accumulatedText.length}chars, masked=${displayText.length}chars`);
                             // }
-                            await sendWeComReply({ wsClient, frame, text: displayText, runtime, finish: false, streamId: state.streamId });
+                            await sendWeComReply({
+                                wsClient,
+                                frame,
+                                text: displayText,
+                                runtime,
+                                finish: false,
+                                streamId: state.streamId,
+                            });
                         }
                         catch (err) {
                             if (err instanceof StreamExpiredError) {
@@ -411,7 +452,13 @@ async function routeAndDispatchMessage(params) {
             },
         });
         // 模板卡片检测与发送（在关闭 thinking 流之前独立处理）
-        const cardResult = await processTemplateCardsIfNeeded({ wsClient, frame, state, account, runtime });
+        const cardResult = await processTemplateCardsIfNeeded({
+            wsClient,
+            frame,
+            state,
+            account,
+            runtime,
+        });
         if (cardResult) {
             // 卡片已发送，用剩余文本替换累积文本
             state.accumulatedText = cardResult.remainingText;
@@ -424,7 +471,13 @@ async function routeAndDispatchMessage(params) {
         runtime.error?.(`[wecom][plugin] Failed to process message: ${String(err)}`);
         // 即使 dispatch 抛异常，也需要处理卡片和关闭 thinking 流
         try {
-            const cardResult = await processTemplateCardsIfNeeded({ wsClient, frame, state, account, runtime });
+            const cardResult = await processTemplateCardsIfNeeded({
+                wsClient,
+                frame,
+                state,
+                account,
+                runtime,
+            });
             if (cardResult) {
                 state.accumulatedText = cardResult.remainingText;
             }
@@ -492,24 +545,43 @@ async function prepareWeComMessage(params) {
         return null;
     }
     // Step 4: 下载并保存图片和文件
-    const [imageMediaList, fileMediaList] = await Promise.all([
-        downloadAndSaveImages({
-            imageUrls,
-            imageAesKeys,
-            account,
-            config,
-            runtime,
-            wsClient,
-        }),
-        downloadAndSaveFiles({
-            fileUrls,
-            fileAesKeys,
-            account,
-            config,
-            runtime,
-            wsClient,
-        }),
-    ]);
+    let imageMediaList;
+    let fileMediaList;
+    try {
+        [imageMediaList, fileMediaList] = await Promise.all([
+            downloadAndSaveImages({
+                imageUrls,
+                imageAesKeys,
+                account,
+                config,
+                runtime,
+                wsClient,
+            }),
+            downloadAndSaveFiles({
+                fileUrls,
+                fileAesKeys,
+                account,
+                config,
+                runtime,
+                wsClient,
+            }),
+        ]);
+    }
+    catch (err) {
+        if (err instanceof MediaOversizeError) {
+            // 附件超过 OpenClaw 配置的大小上限：向用户发送明确的中文提示并终止本次消息处理。
+            const hintText = buildMediaOversizeHintText(err);
+            runtime.error?.(`[wecom] Media oversize: kind=${err.kind}, size=${err.sizeBytes}, max=${err.maxBytes}, filename=${err.filename ?? "(none)"}`);
+            try {
+                await sendWeComReply({ wsClient, frame, text: hintText, runtime, finish: true });
+            }
+            catch (replyErr) {
+                runtime.error?.(`[wecom] Failed to send oversize hint: ${String(replyErr)}`);
+            }
+            return null;
+        }
+        throw err;
+    }
     const mediaList = [...imageMediaList, ...fileMediaList];
     return {
         frame,
@@ -532,7 +604,7 @@ async function prepareWeComMessage(params) {
  * 同一会话中的消息通过串行队列保证按序执行。
  */
 async function processWeComMessageNow(entry) {
-    const { frame, account, config, runtime, wsClient, text, mediaList, quoteContent, messageId, chatId, reqId } = entry;
+    const { frame, account, config, runtime, wsClient, text, mediaList, quoteContent, messageId, chatId, reqId, } = entry;
     // Step 5: 初始化消息状态
     setReqIdForChat(chatId, reqId, account.accountId);
     const streamId = generateReqId("stream");
@@ -547,7 +619,7 @@ async function processWeComMessageNow(entry) {
     //   await sendThinkingReply({ wsClient, frame, streamId, runtime });
     // }
     // Step 7: 构建上下文并路由到核心处理流程（带整体超时保护）
-    const { ctxPayload, route, storePath, chatId: resolvedChatId, chatType } = buildMessageContext(frame, account, config, text, mediaList, quoteContent, runtime);
+    const { ctxPayload, route, storePath, chatId: resolvedChatId, chatType, } = buildMessageContext(frame, account, config, text, mediaList, quoteContent, runtime);
     // 以 sessionKey 为键记录「原始大小写」的 chatId 与 chatType，
     // 供 MCP 工具工厂（index.ts:registerTool）在构造工具闭包时取回，
     // 进而传递给需要原始 chatId 的拦截器（如 doc-auth-error 发送 biz_msg）。

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.2201",
+  "version": "2026.5.7-beta.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -23,6 +23,7 @@
     "prebuild": "npm run clean",
     "release": "node scripts/publish-all.mjs",
     "release:dry": "node scripts/publish-all.mjs --dry-run",
+    "release:ci": "node scripts/publish-all.mjs --yes --restore=no",
     "deploy:local": "bash scripts/dev-deploy.sh"
   },
   "keywords": [
@@ -67,5 +68,13 @@
     "file-type": "^21.3.0",
     "undici": "^7.24.6",
     "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.28"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
   }
 }

package/skills/wecom-doc-manager/SKILL.md

@@ -51,6 +51,7 @@ description: 企业微信文档管理技能。支持企业微信文档、智能
 | errcode | errmsg | 含义 | 处理方式 |
 |---------|--------|------|----------|
 | `851002` | `incompatible doc type` | 文档品类与所调用的接口不匹配 | 根据文档 URL 重新确认品类（参见上方「URL 品类识别与接口路由」表），然后使用该品类对应的正确接口重试 |
+| `851003` | `no authority` | 无权限调用该接口，**智能表格写入场景**下通常是企业可见范围 > 10 人的规模限制 | 若发生在需要写入数据的场景，引导用户走 Webhook 兜底方案，详见 [webhook-fallback.md](../wecom-smartsheet-data/references/webhook-fallback.md)；其他接口则按权限问题排查 |
 
 ## 文档
 

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

@@ -41,14 +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 为字段标题
@@ -58,6 +67,13 @@ 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
 
 删除一行或多行记录，单次必须在 500 行内。**操作不可逆**。record_id 通过 `smartsheet_get_records` 获取。
@@ -69,6 +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` 删除
+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