feishu-user-plugin 1.3.4 → 1.3.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.4",
-  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself (incl. real @-mentions), read chats, manage docs (with image read/write) / bitable / wiki (native + move_docs_to_wiki) / drive / OKR / calendar. 74 tools + 9 skills, 3 auth layers.",
+  "version": "1.3.5",
+  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself (incl. real @-mentions), read chats (with auto-expanded merge_forward), manage docs (with image read/write) / bitable / wiki (native + move_docs_to_wiki) / drive / OKR / calendar. 75 tools + 9 skills, 3 auth layers. v1.3.5: cross-process UAT refresh lock, bot-fallback warning, download_file.",
   "author": {
     "name": "EthanQC"
   },

package/README.md

@@ -6,7 +6,7 @@
 [![Tools](https://img.shields.io/badge/Tools-74-orange.svg)](#tools)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-**All-in-one Feishu/Lark MCP Server -- 74 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, OKR, and more.**
+**All-in-one Feishu/Lark MCP Server -- 75 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, OKR, and more.**
 
 The only MCP server that lets you send messages as your **personal identity** (not a bot), while also integrating the full official Feishu API. Works with Claude Code, Cursor, Windsurf, OpenClaw, and any MCP-compatible client.
 
@@ -337,7 +337,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 }
 ```
 
-## Tools (74 total)
+## Tools (75 total)
 
 ### User Identity -- Messaging (8 tools, cookie auth)
 
@@ -390,7 +390,8 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 | `add_members` | Add users to a group |
 | `remove_members` | Remove users from a group |
 | `upload_image` / `upload_file` | Upload image/file, returns key for sending |
-| `download_image` | Download a chat-message image (message_id + image_key) OR a docx image (image_token + optional doc_token). Returned as MCP image content. |
+| `download_image` | Download a chat-message image (message_id + image_key) OR a docx image (image_token + optional doc_token). Returned as MCP image content. For merge_forward children, use the child's `parentMessageId`, not the child id. |
+| `download_file` | Download a file attachment (msg_type=file). Returns base64 + mimeType + byte count; optional `save_path` writes to disk. Same parent-id rule for merge_forward children. (v1.3.5) |
 
 ### Wiki, OKR, and Calendar (v1.3.4)
 
@@ -508,10 +509,12 @@ Skills are automatically available when the plugin is installed.
 |------------|-------|----------|---------|
 | Cookie | `sl_session` | 12h max-age | Auto-refreshed every 4h via heartbeat |
 | App Token | `tenant_access_token` | 2h | Auto-managed by SDK |
-| User OAuth | `user_access_token` | ~2h | Auto-refreshed via `refresh_token`, saved to `.env` |
+| User OAuth | `user_access_token` | ~2h | Auto-refreshed via `refresh_token`, saved to MCP config |
 
 When the cookie expires (after ~12-24h without heartbeat), re-login at feishu.cn and update `LARK_COOKIE`. Use `get_login_status` to check health proactively.
 
+If UAT refresh fails with `invalid_grant`, re-run `npx feishu-user-plugin oauth` and restart Claude Code / Codex. v1.3.5+ also re-reads the persisted MCP config before refreshing, so duplicate MCP processes can adopt a token already rotated by another process instead of retrying a stale refresh token.
+
 ## Project Structure
 
 ```
@@ -523,7 +526,7 @@ feishu-user-plugin/
 │       ├── SKILL.md         # Main skill definition (trigger, tools, auth)
 │       └── references/      # 8 skill reference docs + CLAUDE.md
 ├── src/
-│   ├── index.js             # MCP server entry point (74 tools)
+│   ├── index.js             # MCP server entry point (75 tools)
 │   ├── client.js            # User identity client (Protobuf gateway)
 │   ├── official.js          # Official API client (REST, UAT)
 │   ├── utils.js             # ID generators, cookie parser

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.4",
-  "description": "All-in-one Feishu plugin for Claude Code & Codex — messaging, docs (with image read/write), bitable, wiki (native + move_docs_to_wiki), drive, OKR, calendar. 74 tools + 9 skills, 3 auth layers.",
+  "version": "1.3.5",
+  "description": "All-in-one Feishu plugin for Claude Code & Codex — messaging (with merge_forward expansion), docs (with image read/write), bitable, wiki (native + move_docs_to_wiki), drive, OKR, calendar. 75 tools + 9 skills, 3 auth layers. v1.3.5: cross-process UAT refresh lock + bot-fallback warning + auto-expand merge_forward + download_file.",
   "main": "src/index.js",
   "bin": {
     "feishu-user-plugin": "src/cli.js"

package/scripts/test-uat-race-child.js

@@ -0,0 +1,24 @@
+// Child worker for test-uat-race.js. Acquires the UAT refresh lock, holds
+// for a brief window (simulating the refresh + persist), then releases.
+// Writes a single line to stdout: "<id> acquired <ts_ms>; released <ts_ms>"
+
+const { LarkOfficialClient } = require('../src/official');
+
+const id = process.argv[2] || '?';
+const holdMs = parseInt(process.argv[3] || '250');
+
+const client = new LarkOfficialClient('test', 'test');
+const lockPath = client._uatLockPath();
+
+(async () => {
+  const got = await client._acquireRefreshLock(lockPath, { timeoutMs: 15000 });
+  if (!got) {
+    console.log(`${id} FAILED_TO_ACQUIRE`);
+    process.exit(1);
+  }
+  const acquired = Date.now();
+  await new Promise(r => setTimeout(r, holdMs));
+  const released = Date.now();
+  client._releaseRefreshLock(lockPath);
+  console.log(`${id} acquired ${acquired}; released ${released}`);
+})().catch(e => { console.log(`${id} ERROR ${e.message}`); process.exit(1); });

package/scripts/test-uat-race.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// Spawn N child processes that all try to hold the UAT refresh lock
+// concurrently. Verify mutual exclusion: no two hold-windows overlap.
+// Exit 0 on PASS, 1 on FAIL.
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const N = 4;
+const HOLD_MS = 300;
+
+const child = path.join(__dirname, 'test-uat-race-child.js');
+
+// Clean up any stale lock from prior runs
+try {
+  const os = require('os');
+  fs.unlinkSync(path.join(os.homedir(), '.claude', 'feishu-uat-refresh.lock'));
+  console.log('(cleaned up stale lock)');
+} catch (_) {}
+
+(async () => {
+  const workers = Array.from({ length: N }, (_, i) => {
+    const p = spawn('node', [child, String(i), String(HOLD_MS)], { stdio: ['ignore', 'pipe', 'inherit'] });
+    let out = '';
+    p.stdout.on('data', d => out += d);
+    return new Promise(resolve => p.on('close', () => resolve(out.trim())));
+  });
+
+  const lines = await Promise.all(workers);
+  console.log('\nraw output:');
+  lines.forEach(l => console.log('  ' + l));
+
+  const events = [];
+  for (const l of lines) {
+    const m = l.match(/^(\d+) acquired (\d+); released (\d+)$/);
+    if (!m) continue;
+    events.push({ id: parseInt(m[1]), acquired: parseInt(m[2]), released: parseInt(m[3]) });
+  }
+
+  if (events.length !== N) {
+    console.log(`\n❌ expected ${N} successful workers, got ${events.length}`);
+    process.exit(1);
+  }
+
+  events.sort((a, b) => a.acquired - b.acquired);
+  console.log('\ntimeline (sorted by acquire):');
+  events.forEach((e, i) => console.log(`  worker ${e.id}: [${e.acquired - events[0].acquired}ms .. ${e.released - events[0].acquired}ms]`));
+
+  let ok = true;
+  for (let i = 1; i < events.length; i++) {
+    const prev = events[i - 1];
+    const curr = events[i];
+    if (curr.acquired < prev.released) {
+      ok = false;
+      console.log(`\n❌ OVERLAP: worker ${prev.id} held until ${prev.released}, worker ${curr.id} acquired at ${curr.acquired} (overlap ${prev.released - curr.acquired}ms)`);
+    }
+  }
+
+  if (ok) {
+    const totalSpan = events[events.length - 1].released - events[0].acquired;
+    const expectedMin = N * HOLD_MS;
+    console.log(`\n✅ mutual exclusion PASSED — ${N} workers serialised in ${totalSpan}ms (expected >= ${expectedMin}ms)`);
+    process.exit(0);
+  } else {
+    process.exit(1);
+  }
+})();

package/skills/feishu-user-plugin/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: feishu-user-plugin
-version: "1.3.4"
-description: "All-in-one Feishu plugin — send messages as yourself, read group/P2P chats, manage docs/tables/wiki (with wiki-node + URL transparent resolution), OKR, calendar, docx image read/write. Replaces and extends the official Feishu MCP."
-allowed-tools: send_to_user, send_to_group, send_as_user, send_image_as_user, send_file_as_user, send_post_as_user, send_sticker_as_user, send_audio_as_user, search_contacts, create_p2p_chat, get_chat_info, get_user_info, get_login_status, read_p2p_messages, list_user_chats, list_chats, read_messages, reply_message, forward_message, search_docs, read_doc, create_doc, list_bitable_tables, list_bitable_fields, search_bitable_records, create_bitable_record, update_bitable_record, list_wiki_spaces, search_wiki, list_wiki_nodes, get_wiki_node, list_files, create_folder, find_user, download_image, list_user_okrs, get_okrs, list_okr_periods, list_calendars, list_calendar_events, get_calendar_event
+version: "1.3.5"
+description: "All-in-one Feishu plugin — send messages as yourself, read group/P2P chats (auto-expands merge_forward), manage docs/tables/wiki (with wiki-node + URL transparent resolution), OKR, calendar, docx image read/write. v1.3.5: cross-process UAT refresh lock, fallback warning, download_file for chat attachments."
+allowed-tools: send_to_user, send_to_group, send_as_user, send_image_as_user, send_file_as_user, send_post_as_user, send_sticker_as_user, send_audio_as_user, search_contacts, create_p2p_chat, get_chat_info, get_user_info, get_login_status, read_p2p_messages, list_user_chats, list_chats, read_messages, reply_message, forward_message, search_docs, read_doc, create_doc, list_bitable_tables, list_bitable_fields, search_bitable_records, create_bitable_record, update_bitable_record, list_wiki_spaces, search_wiki, list_wiki_nodes, get_wiki_node, list_files, create_folder, find_user, download_image, download_file, list_user_okrs, get_okrs, list_okr_periods, list_calendars, list_calendar_events, get_calendar_event
 user_invocable: true
 ---
 

package/skills/feishu-user-plugin/references/CLAUDE.md

@@ -6,7 +6,7 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - **Official API** (app credentials): Read group messages, docs, tables, wiki, drive, contacts, upload files
 - **User OAuth UAT** (user_access_token): Read P2P chat history, list all user's chats
 
-## Tool Categories (74 tools)
+## Tool Categories (75 tools)
 
 ### User Identity — Messaging (reverse-engineered, cookie-based)
 - `send_to_user` — Search user + send text (one step, most common). Returns candidates if multiple matches.
@@ -32,7 +32,7 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - **All docx + bitable + drive create/read/write tools are UAT-first**: when UAT is configured, every operation (create/edit/delete doc blocks, bitable tables/fields/views/records, drive folders) tries the user's token first and falls back to app token on failure. This keeps resources consistently owned by the user and avoids 403 errors when the app can't access user-created resources. Read-only tools (e.g. `read_doc`, `get_doc_blocks`, `list_bitable_tables`) are also UAT-first so user-owned resources remain readable.
 
 ### Official API Tools (app credentials)
-- `list_chats` / `read_messages` — Chat history (read_messages accepts chat name, oc_ ID, or numeric ID; auto-resolves via bot's group list → im.chat.search → search_contacts). **Auto-falls back to UAT for external groups the bot cannot access.** Returns newest messages first by default. Messages include sender names.
+- `list_chats` / `read_messages` — Chat history (read_messages accepts chat name, oc_ ID, or numeric ID; auto-resolves via bot's group list → im.chat.search → search_contacts). **Auto-falls back to UAT for external groups the bot cannot access.** Returns newest messages first by default. Messages include sender names. **v1.3.5**: `merge_forward` messages now auto-expand into their child messages (2 images + 4 texts, with original sender / time / origin chat preserved); text messages get `urls[]` + `feishuDocs[]` extracted so agents can feed them straight into `read_doc` / WebFetch. Disable expansion with `expand_merge_forward=false`.
 - `send_message_as_bot` — Bot sends message to any chat (text, post, interactive, etc.)
 - `reply_message` / `forward_message` — Message operations (as bot)
 - `delete_message` / `update_message` — Recall or edit bot's own messages
@@ -52,7 +52,8 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - `list_files` / `create_folder` — Drive
 - `copy_file` / `move_file` / `delete_file` — Drive file operations (copy, move, delete)
 - `upload_image` / `upload_file` — Upload image/file, returns key for send_image/send_file
-- `download_image` — Download an image and return it as MCP image content so the model **sees the pixels**. Two modes: (1) **message image** — pass `message_id` + `image_key` from read_messages. (2) **docx image** — pass `image_token` (from `get_doc_blocks` image block) and optionally `doc_token` (native id / wiki node / Feishu URL). Tries UAT first, falls back to app token.
+- `download_image` — Download an image and return it as MCP image content so the model **sees the pixels**. Two modes: (1) **message image** — pass `message_id` + `image_key` from read_messages. (2) **docx image** — pass `image_token` (from `get_doc_blocks` image block) and optionally `doc_token` (native id / wiki node / Feishu URL). Tries UAT first, falls back to app token. **merge_forward children**: use the child's `parentMessageId` (NOT the child id) — Feishu returns `File not in msg` with the child id.
+- `download_file` — Download a file (msg_type=file) attachment. Returns base64 + mimeType + byte count; optional `save_path` writes the file to disk. Same parent-id rule for merge_forward children as download_image.
 - `list_user_okrs` / `get_okrs` / `list_okr_periods` — OKR read. UAT-first (works for the authenticated user's OKRs) with app fallback when OKR scope is granted.
 - `list_calendars` / `list_calendar_events` / `get_calendar_event` — Calendar read. UAT-first (primary + shared + subscribed); app identity only sees calendars the bot was explicitly invited to.
 - `find_user` — Contact lookup by email/mobile
@@ -307,7 +308,22 @@ Two known root causes, both fixed in v1.3.3:
 ### If UAT refresh fails with "invalid_grant"
 - The refresh token has expired or been revoked — auto-refresh cannot recover this
 - **Fix**: Re-run OAuth: `npx feishu-user-plugin oauth`
-- Then restart Claude Code
+- Then restart Claude Code / Codex so running MCP server processes load the new token
+- **v1.3.5+ hardening** (no manual action required, fixes the common case):
+  - Cross-process file lock at `~/.claude/feishu-uat-refresh.lock` (`O_CREAT|O_EXCL`, 30 s stale detection) — at most one MCP process refreshes at a time.
+  - Inside the critical section the lock holder re-reads `~/.claude.json` to see if a peer already rotated the token; if so, it adopts the fresh token instead of consuming an already-invalidated refresh token.
+  - This closes the "Codex spawned 6 MCP servers, all shared the same refresh_token, all raced to refresh" failure mode observed on 2026-04-23.
+  - `get_login_status` now does a real UAT health check (calls `listChatsAsUser({pageSize:1})`) — no more "token configured but actually 401" surprises.
+
+### If multiple MCP server processes keep spawning
+- Observed on Codex + Claude Code when the client respawns the server for each tool session without cleaning up the previous one. 6 concurrent `src/index.js` processes is not unusual under heavy use.
+- v1.3.5 neutralises the damage (UAT refresh serialised via file lock) but the stale processes still consume memory.
+- **Manual cleanup when you notice**: `pkill -f 'feishu-user-plugin/src/index.js'` — the client will respawn one fresh process on the next tool call.
+
+### If a create_* tool warns "UAT failed, created as BOT"
+- v1.3.5 added an explicit `⚠️` warning to MCP responses whenever `_asUserOrApp` silently fell back to bot identity for a write (create_doc / create_bitable / create_folder / create_doc_block / ...). Before v1.3.5 this was silent and led to the "teammate can read my 'private' doc" issue.
+- **Cause**: your UAT is failing (expired / scope missing / race) so the plugin reached for bot credentials. The resulting resource is owned by the shared bot, tenant-readable by default, NOT by you.
+- **Fix**: run `npx feishu-user-plugin oauth` and restart Claude Code / Codex. If the resource needs to be yours, delete the bot-owned copy and recreate after UAT is valid.
 
 ### If OAuth fails with "Missing LARK_APP_ID"
 - `oauth.js` reads credentials from `~/.claude.json` MCP config (not .env)

package/src/index.js

@@ -326,7 +326,7 @@ const TOOLS = [
   // ========== IM — Official API (User Identity via UAT) ==========
   {
     name: 'read_p2p_messages',
-    description: '[User UAT] Read P2P (direct message) chat history using user_access_token. Works for chats the bot cannot access. Returns newest messages first by default. Requires OAuth setup.',
+    description: '[User UAT] Read P2P (direct message) chat history using user_access_token. Works for chats the bot cannot access. Returns newest messages first by default. Auto-expands merge_forward messages into their child messages by default — disable with expand_merge_forward=false. Requires OAuth setup.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -335,6 +335,7 @@ const TOOLS = [
         start_time: { type: 'string', description: 'Start timestamp in seconds (optional)' },
         end_time: { type: 'string', description: 'End timestamp in seconds (optional)' },
         sort_type: { type: 'string', enum: ['ByCreateTimeDesc', 'ByCreateTimeAsc'], description: 'Sort order (default: ByCreateTimeDesc = newest first)' },
+        expand_merge_forward: { type: 'boolean', description: 'Auto-expand merge_forward placeholders into their child messages (default true). Children carry parentMessageId; use that id (not the child id) with download_image / download_file.' },
       },
       required: ['chat_id'],
     },
@@ -365,7 +366,7 @@ const TOOLS = [
   },
   {
     name: 'read_messages',
-    description: '[Official API + UAT fallback] Read message history from any group. Accepts oc_xxx ID, numeric ID, or chat name (auto-searched). Auto-falls back to UAT for external groups the bot cannot access. Returns newest messages first by default, with sender names resolved.',
+    description: '[Official API + UAT fallback] Read message history from any group. Accepts oc_xxx ID, numeric ID, or chat name (auto-searched). Auto-falls back to UAT for external groups the bot cannot access. Returns newest messages first by default, with sender names resolved. Auto-expands merge_forward messages into their child messages (with original sender / time / content preserved) by default — disable with expand_merge_forward=false. Text messages have URLs extracted into `urls`; Feishu doc links are additionally surfaced as `feishuDocs` so agents can feed them straight into read_doc / get_doc_blocks.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -374,6 +375,7 @@ const TOOLS = [
         start_time: { type: 'string', description: 'Start timestamp in seconds (optional)' },
         end_time: { type: 'string', description: 'End timestamp in seconds (optional)' },
         sort_type: { type: 'string', enum: ['ByCreateTimeDesc', 'ByCreateTimeAsc'], description: 'Sort order (default: ByCreateTimeDesc = newest first)' },
+        expand_merge_forward: { type: 'boolean', description: 'Auto-expand merge_forward placeholders into their child messages (default true). Children carry parentMessageId; use that id (not the child id) with download_image / download_file.' },
       },
       required: ['chat_id'],
     },
@@ -1013,17 +1015,30 @@ const TOOLS = [
   // ========== Message Resources (Image/File Download) ==========
   {
     name: 'download_image',
-    description: '[User Identity / Official API] Download an image so the model can actually see it. Two modes: (1) message image — pass message_id + image_key from read_messages / read_p2p_messages. (2) docx image — pass doc_token + image_token (the block.image.token from get_doc_blocks). doc_token accepts native document_id, wiki node token, or Feishu URL. Tries user identity first, falls back to app.',
+    description: '[User Identity / Official API] Download an image so the model can actually see it. Two modes: (1) message image — pass message_id + image_key from read_messages / read_p2p_messages. (2) docx image — pass doc_token + image_token (the block.image.token from get_doc_blocks). doc_token accepts native document_id, wiki node token, or Feishu URL. Tries user identity first, falls back to app. NOTE: for merge_forward children, pass the child\'s `parentMessageId` (NOT the child message id) — Feishu keys media by the parent merge_forward id.',
     inputSchema: {
       type: 'object',
       properties: {
-        message_id: { type: 'string', description: 'Message ID (om_xxx) — for mode 1 only' },
+        message_id: { type: 'string', description: 'Message ID (om_xxx) — for mode 1 only. For merge_forward children use the parent merge_forward message id.' },
         image_key: { type: 'string', description: 'Image key (img_xxx) from message content — for mode 1 only' },
         doc_token: { type: 'string', description: 'Document ID, wiki node token, or Feishu URL — for mode 2 only' },
         image_token: { type: 'string', description: 'Image token from a docx image block (block.image.token via get_doc_blocks) — for mode 2 only' },
       },
     },
   },
+  {
+    name: 'download_file',
+    description: '[User Identity / Official API] Download a file attached to a message (msg_type=file). Returns base64 bytes + mimeType + filename. Tries user identity first, falls back to app. For merge_forward children, pass the child\'s `parentMessageId` (NOT the child message id) — Feishu keys media by the parent merge_forward id.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message_id: { type: 'string', description: 'Message ID (om_xxx). For merge_forward children use the parent merge_forward message id.' },
+        file_key: { type: 'string', description: 'File key from message content (content.file_key for msg_type=file)' },
+        save_path: { type: 'string', description: 'Optional absolute local path to save the file to. If omitted, file is only returned as inline base64 in the response.' },
+      },
+      required: ['message_id', 'file_key'],
+    },
+  },
 
   // ========== Wiki Node — Object Resolution (v1.3.4) ==========
   {
@@ -1143,7 +1158,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 
 const text = (s) => ({ content: [{ type: 'text', text: s }] });
-const json = (o) => text(JSON.stringify(o, null, 2));
+const json = (o) => {
+  // If the underlying method surfaced a fallback warning (UAT unavailable,
+  // resource owned by bot), lift it to the top of the response so the human /
+  // agent sees it *before* the structured body. Keeps the JSON payload intact.
+  const warn = o && typeof o === 'object' && o.fallbackWarning ? `${o.fallbackWarning}\n\n` : '';
+  return text(warn + JSON.stringify(o, null, 2));
+};
 const sendResult = (r, desc) => text(r.success ? desc : `Send failed (status: ${r.status})`);
 
 // Resolver helper: turn document_id / app_token / wiki node / Feishu URL into
@@ -1288,7 +1309,17 @@ async function handleTool(name, args) {
           parts.push(`App credentials: INVALID — app_id=${probe.appId} rejected by Feishu (${probe.error})`);
           parts.push(`  → Likely wrong/stale APP_ID. Re-run the install prompt from team-skills/plugins/feishu-user-plugin/README.md to get the correct credentials.`);
         }
-        parts.push(`User access token: ${official.hasUAT ? 'Configured (P2P reading enabled)' : 'Not set (optional — needed for P2P chat reading. Run OAuth flow to obtain, see README for details)'}`);
+        if (official.hasUAT) {
+          try {
+            await official.listChatsAsUser({ pageSize: 1 });
+            parts.push('User access token: Valid (P2P/group UAT reading enabled)');
+          } catch (e) {
+            parts.push(`User access token: INVALID — ${e.message}`);
+            parts.push('  → Re-run OAuth: npx feishu-user-plugin oauth, then restart Claude Code / Codex so running MCP servers load the new token.');
+          }
+        } else {
+          parts.push('User access token: Not set (optional — needed for P2P chat reading. Run OAuth flow to obtain, see README for details)');
+        }
       }
       return text(parts.join('\n'));
     }
@@ -1324,6 +1355,7 @@ async function handleTool(name, args) {
       return json(await official.readMessagesAsUser(chatId, {
         pageSize: args.page_size, startTime: args.start_time, endTime: args.end_time,
         sortType: args.sort_type,
+        expandMergeForward: args.expand_merge_forward !== false,
       }, uc));
     }
     case 'list_user_chats':
@@ -1335,7 +1367,11 @@ async function handleTool(name, args) {
       return json(await getOfficialClient().listChats({ pageSize: args.page_size, pageToken: args.page_token }));
     case 'read_messages': {
       const official = getOfficialClient();
-      const msgOpts = { pageSize: args.page_size, startTime: args.start_time, endTime: args.end_time, sortType: args.sort_type };
+      const msgOpts = {
+        pageSize: args.page_size, startTime: args.start_time, endTime: args.end_time,
+        sortType: args.sort_type,
+        expandMergeForward: args.expand_merge_forward !== false,
+      };
       // Get userClient for name resolution fallback (best-effort)
       let uc = null;
       try { uc = await getUserClient(); } catch (_) {}
@@ -1382,7 +1418,8 @@ async function handleTool(name, args) {
         : r.wikiAttachTaskId ? ` [wiki attach queued — task_id: ${r.wikiAttachTaskId}]`
         : r.wikiAttachError ? ` [WARNING: wiki attach failed — ${r.wikiAttachError}. Doc exists in drive root/folder.]`
         : '';
-      return text(`Document created${ownership}: ${r.documentId}${wikiNote}`);
+      const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+      return text(`Document created${ownership}: ${r.documentId}${wikiNote}${warn}`);
     }
 
     // --- Official API: Bitable ---
@@ -1397,12 +1434,16 @@ async function handleTool(name, args) {
         : r.wikiAttachTaskId ? `\nWiki attach queued — task_id: ${r.wikiAttachTaskId}`
         : r.wikiAttachError ? `\nWARNING: wiki attach failed — ${r.wikiAttachError}. Bitable exists in drive root/folder.`
         : '';
-      return text(`Bitable created${ownership}: ${r.appToken}\nURL: ${r.url || ''}${wikiNote}`);
+      const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+      return text(`Bitable created${ownership}: ${r.appToken}\nURL: ${r.url || ''}${wikiNote}${warn}`);
     }
     case 'list_bitable_tables':
       return json(await getOfficialClient().listBitableTables(await resolveDocId(args.app_token)));
-    case 'create_bitable_table':
-      return text(`Table created: ${(await getOfficialClient().createBitableTable(await resolveDocId(args.app_token), args.name, args.fields)).tableId}`);
+    case 'create_bitable_table': {
+      const r = await getOfficialClient().createBitableTable(await resolveDocId(args.app_token), args.name, args.fields);
+      const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+      return text(`Table created: ${r.tableId}${warn}`);
+    }
     case 'list_bitable_fields':
       return json(await getOfficialClient().listBitableFields(await resolveDocId(args.app_token), args.table_id));
     case 'create_bitable_field': {
@@ -1450,7 +1491,8 @@ async function handleTool(name, args) {
     case 'create_folder': {
       const r = await getOfficialClient().createFolder(args.name, args.parent_token);
       const ownership = r.viaUser ? ' (as user)' : ' (as app — UAT unavailable or failed; folder owned by the app, not you)';
-      return text(`Folder created${ownership}: ${r.token}`);
+      const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+      return text(`Folder created${ownership}: ${r.token}${warn}`);
     }
 
     // --- Official API: Contact ---
@@ -1592,6 +1634,33 @@ async function handleTool(name, args) {
       };
     }
 
+    case 'download_file': {
+      if (!args.message_id || !args.file_key) {
+        return text('download_file requires message_id + file_key. For merge_forward children pass the PARENT merge_forward message id, not the child id.');
+      }
+      const r = await getOfficialClient().downloadMessageResource(args.message_id, args.file_key, 'file');
+      let saveNote = '';
+      if (args.save_path) {
+        try {
+          const fs = require('fs');
+          fs.writeFileSync(args.save_path, Buffer.from(r.base64, 'base64'));
+          saveNote = `\nSaved to: ${args.save_path}`;
+        } catch (e) {
+          saveNote = `\nSave to ${args.save_path} failed: ${e.message}`;
+        }
+      }
+      // Files are returned as a text summary plus a resource link so agents can
+      // either read the saved copy or decode the base64 themselves. We do not
+      // embed binary file content as MCP image blobs (wrong content-type).
+      const summary = `File downloaded from message ${args.message_id} (${r.viaUser ? 'as user' : 'as app'}, ${r.bytes} bytes, ${r.mimeType})${saveNote}`;
+      return {
+        content: [
+          { type: 'text', text: summary },
+          { type: 'text', text: `base64 (${r.bytes} bytes, truncated display):\n${r.base64.slice(0, 400)}${r.base64.length > 400 ? '…' : ''}` },
+        ],
+      };
+    }
+
     // --- Wiki Node Resolution (v1.3.4) ---
     case 'get_wiki_node': {
       // Accept either a bare wiki node token or a full /wiki/ URL — parse first.

package/src/official.js

@@ -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);
@@ -1335,6 +1542,7 @@ 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');
       finalToken = uploaded.fileToken;
@@ -1354,7 +1562,7 @@ 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