feishu-user-plugin 1.3.4 → 1.3.6

package/src/official.js

@@ -1,7 +1,7 @@
 const lark = require('@larksuiteoapi/node-sdk');
 const { fetchWithTimeout } = require('./utils');
 const { classifyError } = require('./error-codes');
-const { buildEmptyImageBlock, buildReplaceImagePayload } = require('./doc-blocks');
+const { buildEmptyImageBlock, buildReplaceImagePayload, buildEmptyFileBlock, buildReplaceFilePayload } = require('./doc-blocks');
 
 // Redirect all Lark SDK logs to stderr.
 // The SDK's defaultLogger.error uses console.log (stdout), which corrupts
@@ -34,7 +34,7 @@ class LarkOfficialClient {
     if (token) {
       this._uat = token;
       this._uatRefresh = refresh || null;
-      this._uatExpires = expires;
+      this._uatExpires = expires || this._decodeTokenExpiry(token);
     }
   }
 
@@ -90,6 +90,7 @@ class LarkOfficialClient {
     if (!this._uat) throw new Error('No user_access_token. Run: npx feishu-user-plugin oauth');
 
     const now = Math.floor(Date.now() / 1000);
+    if (!this._uatExpires) this._uatExpires = this._decodeTokenExpiry(this._uat);
     // Proactively refresh if we know it's expiring within 5 min
     if (this._uatExpires > 0 && this._uatExpires <= now + 300) {
       return this._refreshUAT();
@@ -97,30 +98,125 @@ class LarkOfficialClient {
     return this._uat;
   }
 
+  _decodeTokenExpiry(token) {
+    try {
+      const payload = token?.split('.')?.[1];
+      if (!payload) return 0;
+      const data = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+      return typeof data.exp === 'number' ? data.exp : 0;
+    } catch (_) {
+      return 0;
+    }
+  }
+
+  _adoptPersistedUATIfNewer() {
+    try {
+      const { readCredentials } = require('./config');
+      const creds = readCredentials();
+      const token = creds.LARK_USER_ACCESS_TOKEN;
+      const refresh = creds.LARK_USER_REFRESH_TOKEN;
+      if (!token && !refresh) return false;
+
+      const expires = parseInt(creds.LARK_UAT_EXPIRES || '0') || this._decodeTokenExpiry(token);
+      const changed = (token && token !== this._uat)
+        || (refresh && refresh !== this._uatRefresh)
+        || (expires && expires !== this._uatExpires);
+      if (!changed) return false;
+
+      if (token) this._uat = token;
+      if (refresh) this._uatRefresh = refresh;
+      this._uatExpires = expires || 0;
+      console.error('[feishu-user-plugin] UAT adopted latest persisted token before refresh');
+      return true;
+    } catch (e) {
+      console.error(`[feishu-user-plugin] UAT persisted-token check failed: ${e.message}`);
+      return false;
+    }
+  }
+
+  // Cross-process advisory lock for UAT refresh. Feishu rotates the refresh_token
+  // on every refresh (old one invalidated instantly). When multiple MCP server
+  // processes share the same persisted refresh_token and all wake up near expiry,
+  // they race: the first wins, the rest see `invalid_grant` and can't recover.
+  // This lock serialises refreshes across processes; inside the critical section
+  // we also re-read the persisted config so late arrivals adopt the winner's
+  // token instead of attempting a doomed refresh with the already-rotated one.
+  _uatLockPath() {
+    const path = require('path');
+    const os = require('os');
+    return path.join(os.homedir(), '.claude', 'feishu-uat-refresh.lock');
+  }
+
+  async _acquireRefreshLock(lockPath, { staleMs = 30000, pollMs = 200, timeoutMs = 20000 } = {}) {
+    const fs = require('fs');
+    const path = require('path');
+    try { fs.mkdirSync(path.dirname(lockPath), { recursive: true }); } catch (_) {}
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      try {
+        const fd = fs.openSync(lockPath, 'wx'); // O_CREAT | O_EXCL
+        fs.writeSync(fd, `${process.pid}\n${Date.now()}\n`);
+        fs.closeSync(fd);
+        return true;
+      } catch (e) {
+        if (e.code !== 'EEXIST') throw e;
+        try {
+          const stat = fs.statSync(lockPath);
+          if (Date.now() - stat.mtimeMs > staleMs) {
+            try { fs.unlinkSync(lockPath); } catch (_) {}
+            continue;
+          }
+        } catch (_) { /* lock vanished under us — retry */ }
+        await new Promise(r => setTimeout(r, pollMs));
+      }
+    }
+    return false;
+  }
+
+  _releaseRefreshLock(lockPath) {
+    try { require('fs').unlinkSync(lockPath); } catch (_) {}
+  }
+
   async _refreshUAT() {
-    if (!this._uatRefresh) throw new Error('UAT expired and no refresh token. Run: npx feishu-user-plugin oauth');
+    const lockPath = this._uatLockPath();
+    const acquired = await this._acquireRefreshLock(lockPath);
+    if (!acquired) {
+      console.error('[feishu-user-plugin] UAT refresh lock timed out; proceeding without mutual exclusion');
+    }
+    try {
+      // Re-check under lock: another process may have already refreshed and
+      // persisted a new token while we waited. If so, adopt and skip the refresh.
+      const now = Math.floor(Date.now() / 1000);
+      if (this._adoptPersistedUATIfNewer() && this._uatExpires > now + 300) {
+        return this._uat;
+      }
 
-    const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({
-        grant_type: 'refresh_token',
-        client_id: this.appId,
-        client_secret: this.appSecret,
-        refresh_token: this._uatRefresh,
-      }),
-    });
-    const data = await res.json();
-    const tokenData = data.access_token ? data : data.data;
-    if (!tokenData?.access_token) throw new Error(`UAT refresh failed: ${JSON.stringify(data)}. Run: npx feishu-user-plugin oauth`);
-
-    this._uat = tokenData.access_token;
-    this._uatRefresh = tokenData.refresh_token || this._uatRefresh;
-    const expiresIn = typeof tokenData.expires_in === 'number' && tokenData.expires_in > 0 ? tokenData.expires_in : 7200;
-    this._uatExpires = Math.floor(Date.now() / 1000) + expiresIn;
-    this._persistUAT();
-    console.error('[feishu-user-plugin] UAT refreshed successfully');
-    return this._uat;
+      if (!this._uatRefresh) throw new Error('UAT expired and no refresh token. Run: npx feishu-user-plugin oauth');
+
+      const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          grant_type: 'refresh_token',
+          client_id: this.appId,
+          client_secret: this.appSecret,
+          refresh_token: this._uatRefresh,
+        }),
+      });
+      const data = await res.json();
+      const tokenData = data.access_token ? data : data.data;
+      if (!tokenData?.access_token) throw new Error(`UAT refresh failed: ${JSON.stringify(data)}. Run: npx feishu-user-plugin oauth`);
+
+      this._uat = tokenData.access_token;
+      this._uatRefresh = tokenData.refresh_token || this._uatRefresh;
+      const expiresIn = typeof tokenData.expires_in === 'number' && tokenData.expires_in > 0 ? tokenData.expires_in : 7200;
+      this._uatExpires = Math.floor(Date.now() / 1000) + expiresIn;
+      this._persistUAT();
+      console.error('[feishu-user-plugin] UAT refreshed successfully');
+      return this._uat;
+    } finally {
+      if (acquired) this._releaseRefreshLock(lockPath);
+    }
   }
 
   _persistUAT() {
@@ -210,7 +306,17 @@ class LarkOfficialClient {
     }
     try {
       const appData = await this._safeSDKCall(sdkFn, label);
-      if (appData && typeof appData === 'object') appData._viaUser = false;
+      if (appData && typeof appData === 'object') {
+        appData._viaUser = false;
+        // Attach a warning when we silently fell back to bot identity. This lets
+        // write handlers surface "⚠️ created as BOT, not you" so the user doesn't
+        // discover it days later when a teammate can read the "private" resource.
+        if (uatSummary) {
+          appData._fallbackWarning = `⚠️  UAT 不可用 (${uatSummary}),本次操作以 bot 身份执行。资源归属于共享 bot「Claude聊天助手」,不是你。恢复方法:运行 \`npx feishu-user-plugin oauth\` 后重启 Claude Code / Codex。`;
+        } else if (!this.hasUAT) {
+          appData._fallbackWarning = `⚠️  未配置 UAT,本次操作以 bot 身份执行。资源归属于共享 bot「Claude聊天助手」,不是你。想让资源归你所有,先跑 \`npx feishu-user-plugin oauth\` 然后重启 Claude Code / Codex。`;
+        }
+      }
       return appData;
     } catch (appErr) {
       if (uatSummary) {
@@ -236,7 +342,7 @@ class LarkOfficialClient {
     return { items: data.data.items || [], pageToken: data.data.page_token, hasMore: data.data.has_more };
   }
 
-  async readMessagesAsUser(chatId, { pageSize = 20, startTime, endTime, pageToken, sortType = 'ByCreateTimeDesc' } = {}, userClient) {
+  async readMessagesAsUser(chatId, { pageSize = 20, startTime, endTime, pageToken, sortType = 'ByCreateTimeDesc', expandMergeForward = true } = {}, userClient) {
     // Feishu API requires end_time >= start_time; auto-set end_time to now if missing
     if (startTime && !endTime) {
       endTime = String(Math.floor(Date.now() / 1000));
@@ -257,6 +363,7 @@ class LarkOfficialClient {
     if (data.code !== 0) throw new Error(`readMessagesAsUser failed (${data.code}): ${data.msg}`);
     const items = (data.data.items || []).map(m => this._formatMessage(m));
     await this._populateSenderNames(items, userClient);
+    if (expandMergeForward) await this._expandMergeForwardItems(items, userClient, { preferUAT: true });
     return { items, hasMore: data.data.has_more, pageToken: data.data.page_token };
   }
 
@@ -270,7 +377,7 @@ class LarkOfficialClient {
     return { items: res.data.items || [], pageToken: res.data.page_token, hasMore: res.data.has_more };
   }
 
-  async readMessages(chatId, { pageSize = 20, startTime, endTime, pageToken, sortType = 'ByCreateTimeDesc' } = {}, userClient) {
+  async readMessages(chatId, { pageSize = 20, startTime, endTime, pageToken, sortType = 'ByCreateTimeDesc', expandMergeForward = true } = {}, userClient) {
     const params = { container_id_type: 'chat', container_id: chatId, page_size: pageSize, sort_type: sortType };
     if (startTime) params.start_time = startTime;
     if (endTime) params.end_time = endTime;
@@ -278,6 +385,7 @@ class LarkOfficialClient {
     const res = await this._safeSDKCall(() => this.client.im.message.list({ params }), 'readMessages');
     const items = (res.data.items || []).map(m => this._formatMessage(m));
     await this._populateSenderNames(items, userClient);
+    if (expandMergeForward) await this._expandMergeForwardItems(items, userClient, { preferUAT: false });
     return { items, hasMore: res.data.has_more, pageToken: res.data.page_token };
   }
 
@@ -562,7 +670,7 @@ class LarkOfficialClient {
       label: 'createDoc',
     });
     const documentId = res.data.document?.document_id;
-    const out = { documentId, viaUser: !!res._viaUser };
+    const out = { documentId, viaUser: !!res._viaUser, fallbackWarning: res._fallbackWarning || null };
     if (documentId && wikiSpaceId) {
       try {
         const node = await this.attachToWiki(wikiSpaceId, 'docx', documentId, wikiParentNodeToken);
@@ -598,7 +706,7 @@ class LarkOfficialClient {
       }),
       label: 'createDocBlock',
     });
-    return { blocks: res.data.children || [] };
+    return { blocks: res.data.children || [], fallbackWarning: res._fallbackWarning || null };
   }
 
   async updateDocBlock(documentId, blockId, updateBody) {
@@ -653,7 +761,7 @@ class LarkOfficialClient {
       label: 'createBitable',
     });
     const appToken = res.data.app?.app_token;
-    const out = { appToken, name: res.data.app?.name, url: res.data.app?.url, viaUser: !!res._viaUser };
+    const out = { appToken, name: res.data.app?.name, url: res.data.app?.url, viaUser: !!res._viaUser, fallbackWarning: res._fallbackWarning || null };
     if (appToken && wikiSpaceId) {
       try {
         const node = await this.attachToWiki(wikiSpaceId, 'bitable', appToken, wikiParentNodeToken);
@@ -686,7 +794,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.bitable.appTable.create({ path: { app_token: appToken }, data }),
       label: 'createTable',
     });
-    return { tableId: res.data.table_id };
+    return { tableId: res.data.table_id, fallbackWarning: res._fallbackWarning || null };
   }
 
   async listBitableFields(appToken, tableId) {
@@ -706,7 +814,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.bitable.appTableField.create({ path: { app_token: appToken, table_id: tableId }, data: fieldConfig }),
       label: 'createField',
     });
-    return { field: res.data.field };
+    return { field: res.data.field, fallbackWarning: res._fallbackWarning || null };
   }
 
   async updateBitableField(appToken, tableId, fieldId, fieldConfig) {
@@ -760,7 +868,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.bitable.appTableRecord.create({ path: { app_token: appToken, table_id: tableId }, data: { fields } }),
       label: 'createRecord',
     });
-    return { recordId: res.data.record?.record_id };
+    return { recordId: res.data.record?.record_id, fallbackWarning: res._fallbackWarning || null };
   }
 
   async updateBitableRecord(appToken, tableId, recordId, fields) {
@@ -792,7 +900,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.bitable.appTableRecord.batchCreate({ path: { app_token: appToken, table_id: tableId }, data: { records } }),
       label: 'batchCreateRecords',
     });
-    return { records: res.data.records || [] };
+    return { records: res.data.records || [], fallbackWarning: res._fallbackWarning || null };
   }
 
   async batchUpdateBitableRecords(appToken, tableId, records) {
@@ -874,7 +982,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.bitable.appTableView.create({ path: { app_token: appToken, table_id: tableId }, data: { view_name: viewName, view_type: viewType } }),
       label: 'createView',
     });
-    return { view: res.data.view };
+    return { view: res.data.view, fallbackWarning: res._fallbackWarning || null };
   }
 
   async deleteBitableView(appToken, tableId, viewId) {
@@ -897,7 +1005,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.bitable.app.copy({ path: { app_token: appToken }, data }),
       label: 'copyBitable',
     });
-    return { app: res.data.app };
+    return { app: res.data.app, fallbackWarning: res._fallbackWarning || null };
   }
 
   // --- Wiki ---
@@ -952,7 +1060,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.drive.file.createFolder({ data: body }),
       label: 'createFolder',
     });
-    return { token: res.data.token, viaUser: !!res._viaUser };
+    return { token: res.data.token, viaUser: !!res._viaUser, fallbackWarning: res._fallbackWarning || null };
   }
 
   // --- Drive: File Operations ---
@@ -1110,9 +1218,108 @@ class LarkOfficialClient {
       updateTime: this._normalizeTimestamp(m.update_time),
     };
     if (Array.isArray(m.mentions) && m.mentions.length > 0) out.mentions = m.mentions;
+    if (m.upper_message_id) out.upperMessageId = m.upper_message_id;
+    if (m.root_id) out.rootId = m.root_id;
+    if (m.parent_id) out.parentId = m.parent_id;
+    // Extract URL-like strings from text bodies so agents can call WebFetch /
+    // read_doc / get_doc_blocks without having to regex the body themselves.
+    if (out.msgType === 'text' && typeof body?.text === 'string') {
+      const urls = body.text.match(/https?:\/\/[^\s一-鿿]+/g);
+      if (urls && urls.length > 0) {
+        out.urls = Array.from(new Set(urls));
+        const feishuDocs = out.urls.filter(u =>
+          /feishu\.cn\/(?:docx|wiki|base|sheets|docs|mindnotes)\//i.test(u));
+        if (feishuDocs.length > 0) out.feishuDocs = feishuDocs;
+      }
+    }
     return out;
   }
 
+  // Fetch the child messages inside a merge_forward parent. Feishu exposes them
+  // via `/im/v1/messages/{parent_id}` (single-message GET). The response is
+  // actually a list: items[0] is the parent merge_forward placeholder,
+  // items[1..N] are the children carrying `upper_message_id` pointing back to
+  // the parent and `chat_id` pointing to their ORIGIN chat (the one being
+  // forwarded from, not where the merge_forward was posted).
+  //
+  // Media resources (image_key / file_key) on children must be downloaded
+  // using the PARENT message id — a Feishu quirk: downloading with the child
+  // id returns "File not in msg".
+  async readMergeForwardChildren(parentMessageId, userClient, { preferUAT = true } = {}) {
+    const url = `https://open.feishu.cn/open-apis/im/v1/messages/${encodeURIComponent(parentMessageId)}`;
+
+    const tryPath = async (bearer) => {
+      const res = await fetchWithTimeout(url, {
+        headers: { 'Authorization': `Bearer ${bearer}` },
+        timeoutMs: 30000,
+      });
+      return res.json();
+    };
+
+    let data = null;
+    const order = preferUAT ? ['uat', 'bot'] : ['bot', 'uat'];
+    const errors = [];
+    for (const identity of order) {
+      try {
+        if (identity === 'uat') {
+          if (!this.hasUAT) { errors.push('uat: not configured'); continue; }
+          const uat = await this._getValidUAT();
+          const resp = await tryPath(uat);
+          if (resp.code === 0) { data = resp; break; }
+          errors.push(`uat: code=${resp.code} msg=${resp.msg}`);
+        } else {
+          const tat = await this._getAppToken();
+          const resp = await tryPath(tat);
+          if (resp.code === 0) { data = resp; break; }
+          errors.push(`bot: code=${resp.code} msg=${resp.msg}`);
+        }
+      } catch (e) {
+        errors.push(`${identity}: ${e.message}`);
+      }
+    }
+    if (!data) {
+      throw new Error(`readMergeForwardChildren failed: ${errors.join(' | ')}`);
+    }
+
+    // items[0] is the parent itself — filter it out. The rest are children.
+    const rawChildren = (data.data?.items || []).filter(m =>
+      m.message_id !== parentMessageId && m.upper_message_id);
+
+    const children = rawChildren.map(raw => {
+      const f = this._formatMessage(raw);
+      // Surface the parent id on the child so downstream tools (download_image /
+      // download_file) know which id to pass to Feishu's resource endpoint.
+      f.parentMessageId = parentMessageId;
+      // Mark the origin chat explicitly — child.chatId is the ORIGINAL chat the
+      // message came from, not the chat where the merge_forward was posted.
+      f.originChatId = raw.chat_id;
+      return f;
+    });
+    await this._populateSenderNames(children, userClient);
+    return children;
+  }
+
+  // Expand merge_forward placeholders in-place. Adds `children: [...]` or
+  // `expandError` on each merge_forward item. `depth` guards against nesting
+  // (Feishu does allow nested merge_forward, but we cap at 1 level to avoid
+  // exponential fan-out in agent contexts).
+  async _expandMergeForwardItems(items, userClient, { preferUAT = true, depth = 0, maxDepth = 1 } = {}) {
+    if (!items || depth >= maxDepth) return;
+    for (const m of items) {
+      if (m.msgType !== 'merge_forward') continue;
+      try {
+        const children = await this.readMergeForwardChildren(m.messageId, userClient, { preferUAT });
+        m.children = children;
+        // One extra level deep if user really wants, via recursive call.
+        if (depth + 1 < maxDepth) {
+          await this._expandMergeForwardItems(children, userClient, { preferUAT, depth: depth + 1, maxDepth });
+        }
+      } catch (e) {
+        m.expandError = e.message;
+      }
+    }
+  }
+
   _normalizeTimestamp(ts) {
     if (!ts) return null;
     const n = parseInt(ts);
@@ -1240,17 +1447,36 @@ class LarkOfficialClient {
 
   // --- Docx Image Write (v1.3.4) ---
 
-  // Upload binary media (typically an image) to Feishu's drive layer so it can
-  // be attached to a docx block. Returns the media's file_token, which is what
-  // the image block's `replace_image.token` expects.
+  // Upload binary media to Feishu's drive layer so it can be attached to a
+  // docx block, sheet cell, bitable attachment field, etc. Returns the
+  // media's file_token, which is what the host block's replace_*.token
+  // (or bitable attachment field value) expects.
   //
-  // parentType = 'docx_image' for doc-embedded images (most common).
-  // parentNode = the block_id of the image placeholder (NOT the document_id).
-  async uploadDocMedia(filePath, parentNode, parentType = 'docx_image') {
+  // parentType ∈ {
+  //   docx_image, docx_file,
+  //   sheet_image, sheet_file,
+  //   bitable_image, bitable_file,
+  //   doc_image, doc_file,        // legacy doc (pre-docx)
+  //   ccm_import_open,            // import-task host
+  //   vc_virtual_background       // VC bg, grayscale-only
+  // }
+  // parentNode = the block_id (docx) / spreadsheet_token (sheet) / app_token
+  // (bitable) / doc_token (legacy) — depends on parentType.
+  async uploadMedia(filePath, parentNode, parentType = 'docx_image') {
     const fs = require('fs');
     const path = require('path');
-    if (!filePath) throw new Error('uploadDocMedia: filePath is required');
-    if (!parentNode) throw new Error('uploadDocMedia: parentNode (block_id) is required');
+    if (!filePath) throw new Error('uploadMedia: filePath is required');
+    if (!parentNode) throw new Error('uploadMedia: parentNode is required');
+    const ALLOWED = new Set([
+      'docx_image', 'docx_file',
+      'sheet_image', 'sheet_file',
+      'bitable_image', 'bitable_file',
+      'doc_image', 'doc_file',
+      'ccm_import_open', 'vc_virtual_background',
+    ]);
+    if (!ALLOWED.has(parentType)) {
+      throw new Error(`uploadMedia: unsupported parent_type "${parentType}". Allowed: ${[...ALLOWED].join(', ')}`);
+    }
 
     const stat = fs.statSync(filePath);
     const fileName = path.basename(filePath);
@@ -1258,12 +1484,22 @@ class LarkOfficialClient {
 
     // Best-effort content-type from extension. Feishu doesn't require it but
     // some CDNs behind the API key off it; the Blob default is text/plain
-    // which would look wrong for binary images.
+    // which would look wrong for binary attachments.
     const ext = path.extname(fileName).toLowerCase();
     const mimeMap = {
+      // image
       '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
       '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml',
       '.bmp': 'image/bmp', '.tiff': 'image/tiff', '.ico': 'image/x-icon',
+      // doc / archive
+      '.pdf': 'application/pdf', '.zip': 'application/zip',
+      '.doc': 'application/msword',
+      '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      '.xls': 'application/vnd.ms-excel',
+      '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      '.ppt': 'application/vnd.ms-powerpoint',
+      '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+      '.txt': 'text/plain', '.md': 'text/markdown', '.csv': 'text/csv', '.json': 'application/json',
     };
     const contentType = mimeMap[ext] || 'application/octet-stream';
 
@@ -1283,22 +1519,84 @@ class LarkOfficialClient {
       return res.json();
     };
 
-    // User identity first — docx_image usually belongs to a user-owned doc.
+    // User identity first — host resources are usually user-owned.
+    if (this.hasUAT) {
+      try {
+        const data = await this._withUAT(doUpload);
+        if (data.code === 0 && data.data?.file_token) {
+          return { fileToken: data.data.file_token, viaUser: true };
+        }
+        console.error(`[feishu-user-plugin] uploadMedia (${parentType}) as user failed (${data.code}: ${data.msg}), retrying as app`);
+      } catch (e) {
+        console.error(`[feishu-user-plugin] uploadMedia (${parentType}) as user threw (${e.message}), retrying as app`);
+      }
+    }
+    const appToken = await this._getAppToken();
+    const data = await doUpload(appToken);
+    if (data.code !== 0 || !data.data?.file_token) {
+      throw new Error(`uploadMedia (${parentType}) failed: ${data.code}: ${data.msg || 'no file_token returned'}`);
+    }
+    return { fileToken: data.data.file_token, viaUser: false };
+  }
+
+  // Backwards-compat alias — old name from v1.3.4.
+  async uploadDocMedia(filePath, parentNode, parentType = 'docx_image') {
+    return this.uploadMedia(filePath, parentNode, parentType);
+  }
+
+  // Upload a file to a drive folder (NOT for embedding in a doc — that's
+  // uploadMedia). Uses drive/v1/files/upload_all with parent_type=explorer.
+  // Returns { fileToken, viaUser } where fileToken is the cloud-doc file id.
+  async uploadDriveFile(filePath, folderToken) {
+    const fs = require('fs');
+    const path = require('path');
+    if (!filePath) throw new Error('uploadDriveFile: filePath is required');
+    if (!folderToken) throw new Error('uploadDriveFile: folderToken is required (use the destination folder token; for "my space" root call list_files first to get it)');
+
+    const stat = fs.statSync(filePath);
+    const fileName = path.basename(filePath);
+    const buf = fs.readFileSync(filePath);
+    const ext = path.extname(fileName).toLowerCase();
+    const mimeMap = {
+      '.pdf': 'application/pdf', '.zip': 'application/zip',
+      '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+      '.txt': 'text/plain', '.md': 'text/markdown', '.csv': 'text/csv', '.json': 'application/json',
+      '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    };
+    const contentType = mimeMap[ext] || 'application/octet-stream';
+
+    const doUpload = async (bearer) => {
+      const form = new FormData();
+      form.append('file_name', fileName);
+      form.append('parent_type', 'explorer');
+      form.append('parent_node', folderToken);
+      form.append('size', String(stat.size));
+      form.append('file', new Blob([buf], { type: contentType }), fileName);
+      const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/drive/v1/files/upload_all', {
+        method: 'POST',
+        headers: { 'Authorization': `Bearer ${bearer}` },
+        body: form,
+        timeoutMs: 120000,
+      });
+      return res.json();
+    };
+
     if (this.hasUAT) {
       try {
         const data = await this._withUAT(doUpload);
         if (data.code === 0 && data.data?.file_token) {
           return { fileToken: data.data.file_token, viaUser: true };
         }
-        console.error(`[feishu-user-plugin] uploadDocMedia as user failed (${data.code}: ${data.msg}), retrying as app`);
+        console.error(`[feishu-user-plugin] uploadDriveFile as user failed (${data.code}: ${data.msg}), retrying as app`);
       } catch (e) {
-        console.error(`[feishu-user-plugin] uploadDocMedia as user threw (${e.message}), retrying as app`);
+        console.error(`[feishu-user-plugin] uploadDriveFile as user threw (${e.message}), retrying as app`);
       }
     }
     const appToken = await this._getAppToken();
     const data = await doUpload(appToken);
     if (data.code !== 0 || !data.data?.file_token) {
-      throw new Error(`uploadDocMedia failed: ${data.code}: ${data.msg || 'no file_token returned'}`);
+      throw new Error(`uploadDriveFile failed: ${data.code}: ${data.msg || 'no file_token returned'}`);
     }
     return { fileToken: data.data.file_token, viaUser: false };
   }
@@ -1335,8 +1633,9 @@ class LarkOfficialClient {
     // Step 2 — upload (if needed).
     let finalToken = imageToken;
     let viaUser = !!created._viaUser;
+    let fallbackWarning = created._fallbackWarning || null;
     if (!finalToken) {
-      const uploaded = await this.uploadDocMedia(imagePath, blockId, 'docx_image');
+      const uploaded = await this.uploadMedia(imagePath, blockId, 'docx_image');
       finalToken = uploaded.fileToken;
       viaUser = viaUser && uploaded.viaUser; // true iff both steps went via user
     }
@@ -1354,12 +1653,12 @@ class LarkOfficialClient {
       label: 'createDocBlockWithImage.replaceImage',
     });
 
-    return { blockId, imageToken: finalToken, viaUser };
+    return { blockId, imageToken: finalToken, viaUser, fallbackWarning };
   }
 
   // Replace an existing image block's media token (e.g. swap the picture in an
   // already-created image block). Expects an uploaded media token — use
-  // uploadDocMedia or create_doc_block's image_path shortcut to obtain one.
+  // uploadMedia or create_doc_block's image_path shortcut to obtain one.
   async updateDocBlockImage(documentId, blockId, imageToken) {
     const patch = buildReplaceImagePayload(imageToken);
     await this._asUserOrApp({
@@ -1375,6 +1674,125 @@ class LarkOfficialClient {
     return { blockId, imageToken };
   }
 
+  // Create a file-attachment block in a docx, mirroring createDocBlockWithImage:
+  //   1) create empty file placeholder block
+  //   2) upload the binary via uploadMedia(parent_type=docx_file)
+  //   3) PATCH with replace_file.token to attach
+  // Returns { blockId, fileToken, viaUser, fallbackWarning }.
+  async createDocBlockWithFile(documentId, parentBlockId, { filePath, fileToken, index } = {}) {
+    if (!filePath && !fileToken) {
+      throw new Error('createDocBlockWithFile: either filePath or fileToken is required');
+    }
+    const placeholder = buildEmptyFileBlock();
+    const createBody = { children: [placeholder] };
+    if (index !== undefined) createBody.index = index;
+    const created = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${parentBlockId}/children`,
+      method: 'POST',
+      body: createBody,
+      sdkFn: () => this.client.docx.documentBlockChildren.create({
+        path: { document_id: documentId, block_id: parentBlockId },
+        data: createBody,
+      }),
+      label: 'createDocBlockWithFile.placeholder',
+    });
+    // Feishu auto-wraps a FILE block (block_type=23) in a VIEW block
+    // (block_type=33) — the create response returns the OUTER view block.
+    // We need the inner file block's id for both the media upload (parent_node)
+    // and the replace_file PATCH. Walk children to find it; fall back to a
+    // get_doc_blocks lookup if the response didn't materialize the descendant.
+    const newBlock = (created.data.children || [])[0];
+    const outerBlockId = newBlock?.block_id;
+    if (!outerBlockId) throw new Error(`createDocBlockWithFile: placeholder creation returned no block_id: ${JSON.stringify(created.data).slice(0, 400)}`);
+    // Feishu auto-wraps a FILE block (23) in a VIEW block (33). The create
+    // response's outer block is the view; we need to find the inner file
+    // block for both the media upload (parent_node) and the replace_file PATCH.
+    let blockId = outerBlockId;
+    if (newBlock.block_type !== 23) {
+      const inner = await this._findFileChildOf(documentId, outerBlockId, newBlock.children);
+      if (!inner) throw new Error(`createDocBlockWithFile: could not locate inner FILE block under view ${outerBlockId}`);
+      blockId = inner;
+    }
+
+    let finalToken = fileToken;
+    let viaUser = !!created._viaUser;
+    let fallbackWarning = created._fallbackWarning || null;
+    if (!finalToken) {
+      const uploaded = await this.uploadMedia(filePath, blockId, 'docx_file');
+      finalToken = uploaded.fileToken;
+      viaUser = viaUser && uploaded.viaUser;
+    }
+
+    const patch = buildReplaceFilePayload(finalToken);
+    await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}`,
+      method: 'PATCH',
+      body: patch,
+      sdkFn: () => this.client.docx.documentBlock.patch({
+        path: { document_id: documentId, block_id: blockId },
+        data: patch,
+      }),
+      label: 'createDocBlockWithFile.replaceFile',
+    });
+
+    return { blockId, viewBlockId: outerBlockId !== blockId ? outerBlockId : undefined, fileToken: finalToken, viaUser, fallbackWarning };
+  }
+
+  // Helper for createDocBlockWithFile — given a view block id and the children
+  // array surfaced by the create response (just IDs in docx v1), find the
+  // FILE child (block_type=23). If no children list was returned, fall back
+  // to listing the doc and walking by parent_id.
+  async _findFileChildOf(documentId, viewBlockId, childIds) {
+    if (Array.isArray(childIds) && childIds.length > 0) {
+      // childIds[0] is most likely the file block — verify with a get
+      for (const childId of childIds) {
+        try {
+          const res = await this._asUserOrApp({
+            uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${childId}`,
+            method: 'GET',
+            sdkFn: () => this.client.docx.documentBlock.get({ path: { document_id: documentId, block_id: childId } }),
+            label: '_findFileChildOf.get',
+          });
+          if (res?.data?.block?.block_type === 23) return childId;
+        } catch (_) { /* fall through */ }
+      }
+      // None matched directly; return the first as best-effort
+      return childIds[0];
+    }
+    // Fallback: list all blocks and find a 23 whose parent_id is the view block
+    try {
+      const res = await this._asUserOrApp({
+        uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks`,
+        method: 'GET',
+        sdkFn: () => this.client.docx.documentBlock.list({ path: { document_id: documentId } }),
+        label: '_findFileChildOf.list',
+      });
+      const items = res?.data?.items || [];
+      const match = items.find(b => b.block_type === 23 && b.parent_id === viewBlockId);
+      return match?.block_id || null;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  // Replace an existing file block's media token. Expects an already-uploaded
+  // file token (use uploadMedia with parent_type=docx_file, or
+  // create_doc_block's file_path shortcut).
+  async updateDocBlockFile(documentId, blockId, fileToken) {
+    const patch = buildReplaceFilePayload(fileToken);
+    await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}`,
+      method: 'PATCH',
+      body: patch,
+      sdkFn: () => this.client.docx.documentBlock.patch({
+        path: { document_id: documentId, block_id: blockId },
+        data: patch,
+      }),
+      label: 'updateDocBlockFile',
+    });
+    return { blockId, fileToken };
+  }
+
   // --- Wiki attach (v1.3.4) ---
 
   // Move an existing drive resource (docx / bitable / sheet / ...) into a Wiki