feishu-user-plugin 1.3.2 → 1.3.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.2",
-  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself (incl. real @-mentions), read chats, manage docs/tables/wiki. 66 tools + 9 skills, 3 auth layers.",
+  "version": "1.3.3",
+  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself (incl. real @-mentions), read chats, manage docs/tables/wiki. 67 tools + 9 skills, 3 auth layers.",
   "author": {
     "name": "EthanQC"
   },

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.3.3] - 2026-04-20
+
+### Fixed
+- **MCP mid-session disconnect (root fix)**: All raw `fetch` calls to Feishu now go through `fetchWithTimeout` (AbortController, 30s default). A stalled connection used to hang a tool handler indefinitely; the MCP client would time out and some clients tore down the stdio transport — observed as "MCP 中途掉线" on v1.3.2. This was the real cause, not just the v1.3.1 stdout pollution.
+- **stdout pollution (defense-in-depth)**: `src/index.js` now globally redirects `console.log` / `console.info` to stderr at startup, before any other `require`. Any current or future dependency that accidentally writes to stdout can no longer corrupt the JSON-RPC channel. (v1.3.1's Lark-SDK-specific logger override stays as-is.)
+- **`(as user)` label lied for docs/bitable/folder creation**: `create_doc` / `create_bitable` / `create_folder` previously labeled every successful call `(as user)` whenever `LARK_USER_ACCESS_TOKEN` was set, even when the UAT call actually failed and silently fell back to app identity. `_asUserOrApp` now threads a real `_viaUser` flag through; failures show `(as app — UAT unavailable or failed; <resource> owned by the app, not you)`.
+
+### Added
+- **APP_ID startup validation**: MCP server probes `/auth/v3/app_access_token/internal` at boot. Invalid `LARK_APP_ID` / `LARK_APP_SECRET` (wrong-tenant, stale, or hallucinated by an autoinstall) now produce a clear stderr error pointing at the team-skills install prompt. Non-blocking — users running cookie-only workflows are unaffected.
+- **`get_login_status` shows app identity**: Now returns the actual `app_id` plus fetched app name, so users can immediately spot "this isn't my team's app" scenarios.
+- **`download_image` tool**: Download an image embedded in a message by `message_id` + `image_key`, returned as MCP image content so the model can see the pixels (not just the key string). Tries UAT first (works for any chat the user is in); falls back to app token (requires the bot to be in the chat).
+
+### Changed
+- Tool count 66 → **67** (added `download_image`).
+- README tool badge corrected from 76 → 67 (previous 76 was stale and never matched the actual export).
+
 ## [1.1.3] - 2026-03-11
 
 ### Fixed

package/README.md

@@ -3,10 +3,10 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org)
 [![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
-[![Tools](https://img.shields.io/badge/Tools-76-orange.svg)](#tools)
+[![Tools](https://img.shields.io/badge/Tools-67-orange.svg)](#tools)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-**All-in-one Feishu/Lark MCP Server -- 76 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, and more.**
+**All-in-one Feishu/Lark MCP Server -- 67 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, 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 (76 total)
+## Tools (67 total)
 
 ### User Identity -- Messaging (8 tools, cookie auth)
 
@@ -390,6 +390,7 @@ 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 an image from a message by message_id + image_key, returned as MCP image content so the model can see the pixels |
 
 ### Official API -- Documents (7 tools)
 
@@ -508,7 +509,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 (76 tools)
+│   ├── index.js             # MCP server entry point (67 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.2",
-  "description": "All-in-one Feishu plugin for Claude Code & Codex — messaging, docs, bitable, wiki, drive. 66 tools + 9 skills, 3 auth layers.",
+  "version": "1.3.3",
+  "description": "All-in-one Feishu plugin for Claude Code & Codex — messaging, docs, bitable, wiki, drive. 67 tools + 9 skills, 3 auth layers.",
   "main": "src/index.js",
   "bin": {
     "feishu-user-plugin": "src/cli.js"

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

@@ -1,8 +1,8 @@
 ---
 name: feishu-user-plugin
-version: "1.1.3"
-description: "All-in-one Feishu plugin — send messages as yourself, read group/P2P chats, manage docs/tables/wiki. 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, list_files, create_folder, find_user
+version: "1.3.3"
+description: "All-in-one Feishu plugin — send messages as yourself, read group/P2P chats, manage docs/tables/wiki, download images. 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, list_files, create_folder, find_user, download_image
 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 (66 tools)
+## Tool Categories (67 tools)
 
 ### User Identity — Messaging (reverse-engineered, cookie-based)
 - `send_to_user` — Search user + send text (one step, most common). Returns candidates if multiple matches.
@@ -52,6 +52,7 @@ 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 from a message (needs message_id + image_key from read_messages) and return it as MCP image content so the model can **see the pixels**, not just the key. Tries UAT first, falls back to app token (app path requires the bot to be in the chat).
 - `find_user` — Contact lookup by email/mobile
 
 ## Usage Patterns
@@ -233,9 +234,21 @@ Tell user to restart Claude Code. Only ONE restart should be needed.
 ## Troubleshooting Guide
 
 ### If MCP disconnects mid-session
-- **Root cause** (fixed in v1.3.1): `@larksuiteoapi/node-sdk`'s `defaultLogger.error` uses `console.log` (stdout). MCP protocol uses stdout for JSON-RPC, so SDK error logs corrupt the transport and cause immediate disconnect.
-- **Fix**: Custom logger redirects all SDK output to stderr. Already applied in `src/official.js`.
-- If still happening: check for any `console.log` calls in server code (only `console.error` is safe in MCP servers).
+Two known root causes, both fixed in v1.3.3:
+
+1. **stdout pollution** (partial fix in v1.3.1, fully closed in v1.3.3):
+   - `@larksuiteoapi/node-sdk`'s `defaultLogger.error` uses `console.log` (stdout). MCP uses stdout for JSON-RPC, so any stray write corrupts the transport and disconnects the client.
+   - v1.3.1 replaced the SDK's logger. v1.3.3 also globally redirects `console.log` / `console.info` → `console.error` at the top of `src/index.js` as defense-in-depth against ANY future dependency leaking to stdout.
+
+2. **unbounded fetch hangs** (fixed in v1.3.3):
+   - All raw `fetch` calls to `feishu.cn` / `internal-api-lark-api.feishu.cn` used to have no timeout. A stalled connection (ECONNRESET, slow DNS, upstream hang) would block a tool handler indefinitely; the MCP client times out the request, which some clients handle by tearing down the stdio transport — observed as "mid-session disconnect".
+   - Fix: `utils.js::fetchWithTimeout` with `AbortController`, 30s default. All `client.js` + `official.js` fetches go through it.
+   - If still happening: check for any `console.log` calls in server code (only `console.error` is safe), and grep for raw `await fetch(` — every one must go through `fetchWithTimeout`.
+
+### If Official API tools return 401 / "token invalid" every time
+- **Likely cause**: `LARK_APP_ID` is wrong or stale. Observed in production: Claude Code auto-installed the plugin and guessed/copied a wrong APP_ID that doesn't match the team's real app (e.g. from an unrelated app, from someone else's machine, or hallucinated).
+- **Diagnosis**: `get_login_status` now reports `App credentials: INVALID — app_id=<x> rejected by Feishu (<code>: <msg>)`. MCP startup logs `[feishu-user-plugin] ERROR: LARK_APP_ID=<x> was REJECTED by Feishu` on stderr when this happens.
+- **Fix**: Re-run the canonical install prompt from `team-skills/plugins/feishu-user-plugin/README.md` which contains the correct APP_ID/SECRET, and restart Claude Code.
 
 ### If MCP tools are not available
 1. Check `~/.claude.json` — config must be in **top-level** `mcpServers`, not inside `projects[*]`

package/src/client.js

@@ -1,6 +1,6 @@
 const path = require('path');
 const protobuf = require('protobufjs');
-const { generateRequestId, generateCid, parseCookie, formatCookie } = require('./utils');
+const { generateRequestId, generateCid, parseCookie, formatCookie, fetchWithTimeout } = require('./utils');
 
 const GATEWAY_URL = 'https://internal-api-lark-api.feishu.cn/im/gateway/';
 const CSRF_URL = 'https://internal-api-lark-api.feishu.cn/accounts/csrf';
@@ -47,7 +47,7 @@ class LarkUserClient {
   // --- Auth ---
 
   async _getCsrfToken() {
-    const res = await fetch(`${CSRF_URL}?_t=${Date.now()}`, {
+    const res = await fetchWithTimeout(`${CSRF_URL}?_t=${Date.now()}`, {
       method: 'POST',
       headers: {
         ...this._jsonHeaders(),
@@ -68,7 +68,7 @@ class LarkUserClient {
   }
 
   async _getUserInfo() {
-    const res = await fetch(`${USER_INFO_URL}?app_id=12&_t=${Date.now()}`, {
+    const res = await fetchWithTimeout(`${USER_INFO_URL}?app_id=12&_t=${Date.now()}`, {
       headers: {
         ...this._jsonHeaders(),
         'x-csrf-token': this.csrfToken || '',
@@ -179,7 +179,7 @@ class LarkUserClient {
       cid: generateRequestId(),
       payload: reqBuf,
     });
-    const res = await fetch(GATEWAY_URL, {
+    const res = await fetchWithTimeout(GATEWAY_URL, {
       method: 'POST',
       headers: this._protoHeaders(cmd, cmdVersion),
       body: packetBuf,

package/src/index.js

@@ -1,4 +1,14 @@
 #!/usr/bin/env node
+// MCP stdio protocol uses stdout for JSON-RPC. ANY accidental stdout write from
+// this process or its dependencies will corrupt the transport and disconnect the
+// client. v1.3.1 patched the Lark SDK's defaultLogger via a custom logger, but
+// that only covers one dependency. This global redirect is defense-in-depth:
+// any present or future module that calls console.log (or console.info) goes to
+// stderr instead, so MCP stdio stays clean no matter what.
+// Do this BEFORE any other require() so even early log calls are captured.
+console.log = (...args) => console.error(...args);
+console.info = (...args) => console.error(...args);
+
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const {
@@ -992,6 +1002,20 @@ const TOOLS = [
     },
   },
 
+  // ========== Message Resources (Image/File Download) ==========
+  {
+    name: 'download_image',
+    description: '[User Identity / Official API] Download an image embedded in a message so the model can actually see it. Pass the message_id and image_key returned by read_messages / read_p2p_messages. Tries user identity first (works for any chat the user sees), falls back to app identity (requires the bot to be in the same chat).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message_id: { type: 'string', description: 'The message_id (om_xxx) that contains the image — from read_messages / read_p2p_messages' },
+        image_key: { type: 'string', description: 'The image_key from the message content (img_xxx)' },
+      },
+      required: ['message_id', 'image_key'],
+    },
+  },
+
 ];
 
 // --- Server ---
@@ -1139,9 +1163,20 @@ async function handleTool(name, args) {
         parts.push(`  ${status.message}`);
       } catch (e) { parts.push(`Cookie: ${e.message}`); }
       const hasApp = !!(process.env.LARK_APP_ID && process.env.LARK_APP_SECRET);
-      parts.push(`App credentials: ${hasApp ? 'Configured' : 'Not set'}`);
-      const official = hasApp ? getOfficialClient() : null;
-      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 (!hasApp) {
+        parts.push(`App credentials: Not set`);
+      } else {
+        const official = getOfficialClient();
+        const probe = await official.verifyApp();
+        if (probe.valid) {
+          const nameBit = probe.appName ? ` "${probe.appName}"` : '';
+          parts.push(`App credentials: Valid — app_id=${probe.appId}${nameBit}`);
+        } else {
+          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)'}`);
+      }
       return text(parts.join('\n'));
     }
 
@@ -1236,17 +1271,16 @@ async function handleTool(name, args) {
     case 'get_doc_blocks':
       return json(await getOfficialClient().getDocBlocks(args.document_id));
     case 'create_doc': {
-      const official = getOfficialClient();
-      const ownership = official.hasUAT ? ' (as user)' : '';
-      return text(`Document created${ownership}: ${(await official.createDoc(args.title, args.folder_id)).documentId}`);
+      const r = await getOfficialClient().createDoc(args.title, args.folder_id);
+      const ownership = r.viaUser ? ' (as user)' : ' (as app — UAT unavailable or failed; document owned by the app, not you)';
+      return text(`Document created${ownership}: ${r.documentId}`);
     }
 
     // --- Official API: Bitable ---
 
     case 'create_bitable': {
-      const official = getOfficialClient();
-      const ownership = official.hasUAT ? ' (as user)' : '';
-      const r = await official.createBitable(args.name, args.folder_id);
+      const r = await getOfficialClient().createBitable(args.name, args.folder_id);
+      const ownership = r.viaUser ? ' (as user)' : ' (as app — UAT unavailable or failed; bitable owned by the app, not you)';
       return text(`Bitable created${ownership}: ${r.appToken}\nURL: ${r.url || ''}`);
     }
     case 'list_bitable_tables':
@@ -1298,9 +1332,9 @@ async function handleTool(name, args) {
     case 'list_files':
       return json(await getOfficialClient().listFiles(args.folder_token));
     case 'create_folder': {
-      const official = getOfficialClient();
-      const ownership = official.hasUAT ? ' (as user)' : '';
-      return text(`Folder created${ownership}: ${(await official.createFolder(args.name, args.parent_token)).token}`);
+      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}`);
     }
 
     // --- Official API: Contact ---
@@ -1393,6 +1427,18 @@ async function handleTool(name, args) {
     case 'delete_file':
       return text(`File deleted: task=${(await getOfficialClient().deleteFile(args.file_token, args.type)).taskId}`);
 
+    case 'download_image': {
+      const r = await getOfficialClient().downloadMessageResource(args.message_id, args.image_key, 'image');
+      // Return as MCP image content so the model sees the pixels directly.
+      // Also include a tiny text preamble so the via-identity + size are visible in transcript.
+      return {
+        content: [
+          { type: 'text', text: `Image downloaded (${r.viaUser ? 'as user' : 'as app'}, ${r.bytes} bytes, ${r.mimeType}):` },
+          { type: 'image', data: r.base64, mimeType: r.mimeType },
+        ],
+      };
+    }
+
     default:
       return text(`Unknown tool: ${name}`);
   }
@@ -1422,6 +1468,27 @@ async function main() {
   if (!hasCookie) console.error('[feishu-user-plugin] WARNING: LARK_COOKIE not set — user identity tools (send_to_user, etc.) will fail');
   if (!hasApp) console.error('[feishu-user-plugin] WARNING: LARK_APP_ID/SECRET not set — official API tools (read_messages, docs, etc.) will fail');
   if (!hasUAT) console.error('[feishu-user-plugin] WARNING: LARK_USER_ACCESS_TOKEN not set — P2P chat reading (read_p2p_messages) will fail');
+
+  // Validate APP_ID/SECRET against Feishu before serving any tool calls.
+  // Catches the "Claude filled in a wrong/stale APP_ID during install" failure mode
+  // that otherwise surfaces as cryptic 401s on every Official API call (looks like
+  // "MCP 掉线" to the user). Non-blocking — we warn but still serve, because the
+  // user may only need user-identity (cookie) tools.
+  if (hasApp) {
+    try {
+      const probe = await getOfficialClient().verifyApp();
+      if (probe.valid) {
+        const nameBit = probe.appName ? ` "${probe.appName}"` : '';
+        console.error(`[feishu-user-plugin] App verified: ${probe.appId}${nameBit}`);
+      } else {
+        console.error(`[feishu-user-plugin] ERROR: LARK_APP_ID=${probe.appId} was REJECTED by Feishu (${probe.error}).`);
+        console.error('[feishu-user-plugin] → Every Official API tool call will fail. Likely wrong/stale APP_ID.');
+        console.error('[feishu-user-plugin] → Re-run the install prompt from team-skills/plugins/feishu-user-plugin/README.md to get the correct credentials.');
+      }
+    } catch (e) {
+      console.error(`[feishu-user-plugin] WARNING: Could not verify APP_ID (${e.message}); network issue or cold start. Proceeding anyway.`);
+    }
+  }
 }
 
 main().catch(console.error);

package/src/official.js

@@ -1,4 +1,5 @@
 const lark = require('@larksuiteoapi/node-sdk');
+const { fetchWithTimeout } = require('./utils');
 
 // Redirect all Lark SDK logs to stderr.
 // The SDK's defaultLogger.error uses console.log (stdout), which corrupts
@@ -39,6 +40,50 @@ class LarkOfficialClient {
     return !!this._uat;
   }
 
+  // Fetches (and caches) an app_access_token directly via the internal endpoint.
+  // Avoids relying on SDK-internal token-manager APIs that may change across versions.
+  async _getAppToken() {
+    const now = Math.floor(Date.now() / 1000);
+    if (this._appToken && this._appTokenExpires > now + 60) return this._appToken;
+    const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ app_id: this.appId, app_secret: this.appSecret }),
+      timeoutMs: 10000,
+    });
+    const data = await res.json();
+    if (data.code !== 0 || !data.app_access_token) {
+      throw new Error(`app_access_token failed: ${data.code}: ${data.msg || 'unknown'}`);
+    }
+    this._appToken = data.app_access_token;
+    this._appTokenExpires = now + (typeof data.expire === 'number' ? data.expire : 7200);
+    return this._appToken;
+  }
+
+  // Probe APP_ID/SECRET validity by requesting a tenant access token.
+  // Catches the common "user's Claude filled in a wrong/stale APP_ID" failure mode
+  // (observed in production: 周宇's machine ran with an APP_ID nobody recognized,
+  // causing all Official API calls to 401 with cryptic messages that looked like
+  // MCP "掉线" to the user). Returns { valid, appId, appName?, error? }.
+  async verifyApp() {
+    try {
+      const token = await this._getAppToken();
+      // Try to fetch app display name (best-effort; requires application scope)
+      let appName = null;
+      try {
+        const infoRes = await fetchWithTimeout(`https://open.feishu.cn/open-apis/application/v6/applications/${this.appId}?lang=zh_cn`, {
+          headers: { 'Authorization': `Bearer ${token}` },
+          timeoutMs: 10000,
+        });
+        const info = await infoRes.json();
+        if (info.code === 0) appName = info.data?.app?.app_name || null;
+      } catch (_) { /* name is best-effort; valid creds still matter most */ }
+      return { valid: true, appId: this.appId, appName };
+    } catch (e) {
+      return { valid: false, appId: this.appId, error: e.message };
+    }
+  }
+
   async _getValidUAT() {
     if (!this._uat) throw new Error('No user_access_token. Run: npx feishu-user-plugin oauth');
 
@@ -53,7 +98,7 @@ class LarkOfficialClient {
   async _refreshUAT() {
     if (!this._uatRefresh) throw new Error('UAT expired and no refresh token. Run: npx feishu-user-plugin oauth');
 
-    const res = await fetch('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
+    const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({
@@ -112,31 +157,38 @@ class LarkOfficialClient {
         headers['content-type'] = 'application/json';
         init.body = JSON.stringify(body);
       }
-      const res = await fetch(url, init);
+      const res = await fetchWithTimeout(url, init);
       return res.json();
     });
   }
 
   // Try UAT first (for resources likely owned by the user), fall back to app SDK on failure.
-  // Returns SDK-shaped {code, msg, data}. Both paths yield the same shape.
+  // Returns SDK-shaped {code, msg, data, _viaUser}. _viaUser is true iff the UAT call succeeded;
+  // callers can surface this to distinguish "created by user" vs "created by app" for resources
+  // whose ownership matters (docs, bitables, folders).
   async _asUserOrApp({ uatPath, method = 'GET', body, query, sdkFn, label }) {
     if (this.hasUAT) {
       try {
         const data = await this._uatREST(method, uatPath, { body, query });
-        if (data.code === 0) return data;
+        if (data.code === 0) {
+          data._viaUser = true;
+          return data;
+        }
         console.error(`[feishu-user-plugin] ${label} as user failed (${data.code}: ${data.msg}), retrying as app`);
       } catch (err) {
         console.error(`[feishu-user-plugin] ${label} as user threw (${err.message}), retrying as app`);
       }
     }
-    return this._safeSDKCall(sdkFn, label);
+    const appData = await this._safeSDKCall(sdkFn, label);
+    if (appData && typeof appData === 'object') appData._viaUser = false;
+    return appData;
   }
 
   async listChatsAsUser({ pageSize = 20, pageToken } = {}) {
     const params = new URLSearchParams({ page_size: String(pageSize) });
     if (pageToken) params.set('page_token', pageToken);
     const data = await this._withUAT(async (uat) => {
-      const res = await fetch(`https://open.feishu.cn/open-apis/im/v1/chats?${params}`, {
+      const res = await fetchWithTimeout(`https://open.feishu.cn/open-apis/im/v1/chats?${params}`, {
         headers: { 'Authorization': `Bearer ${uat}` },
       });
       return res.json();
@@ -158,7 +210,7 @@ class LarkOfficialClient {
     if (endTime) params.set('end_time', endTime);
     if (pageToken) params.set('page_token', pageToken);
     const data = await this._withUAT(async (uat) => {
-      const res = await fetch(`https://open.feishu.cn/open-apis/im/v1/messages?${params}`, {
+      const res = await fetchWithTimeout(`https://open.feishu.cn/open-apis/im/v1/messages?${params}`, {
         headers: { 'Authorization': `Bearer ${uat}` },
       });
       return res.json();
@@ -198,6 +250,57 @@ class LarkOfficialClient {
     return this._formatMessage(res.data);
   }
 
+  // Download a resource (image/file) attached to a message.
+  // Tries UAT first (works for any chat the user is in), falls back to app token
+  // (requires the bot to be in the same chat — Feishu restriction).
+  // resourceType: 'image' | 'file'. Returns { base64, mimeType, viaUser }.
+  async downloadMessageResource(messageId, fileKey, resourceType = 'image') {
+    const path = `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}/resources/${encodeURIComponent(fileKey)}?type=${encodeURIComponent(resourceType)}`;
+    const url = 'https://open.feishu.cn' + path;
+
+    // Attempt 1: user identity
+    if (this.hasUAT) {
+      try {
+        const uat = await this._getValidUAT();
+        const res = await fetchWithTimeout(url, {
+          headers: { 'Authorization': `Bearer ${uat}` },
+          timeoutMs: 60000,
+        });
+        if (res.ok && !res.headers.get('content-type')?.includes('application/json')) {
+          const buf = Buffer.from(await res.arrayBuffer());
+          return {
+            base64: buf.toString('base64'),
+            mimeType: res.headers.get('content-type') || 'application/octet-stream',
+            bytes: buf.length,
+            viaUser: true,
+          };
+        }
+        const errJson = await res.json().catch(() => null);
+        console.error(`[feishu-user-plugin] downloadMessageResource as user failed: ${errJson?.code}: ${errJson?.msg || res.statusText}, retrying as app`);
+      } catch (e) {
+        console.error(`[feishu-user-plugin] downloadMessageResource as user threw (${e.message}), retrying as app`);
+      }
+    }
+
+    // Attempt 2: app identity
+    const token = await this._getAppToken();
+    const res = await fetchWithTimeout(url, {
+      headers: { 'Authorization': `Bearer ${token}` },
+      timeoutMs: 60000,
+    });
+    if (!res.ok || res.headers.get('content-type')?.includes('application/json')) {
+      const errJson = await res.json().catch(() => null);
+      throw new Error(`downloadMessageResource failed: ${errJson?.code}: ${errJson?.msg || res.statusText}. Note: app identity requires the bot to be in the same chat.`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    return {
+      base64: buf.toString('base64'),
+      mimeType: res.headers.get('content-type') || 'application/octet-stream',
+      bytes: buf.length,
+      viaUser: false,
+    };
+  }
+
   async replyMessage(messageId, text, msgType = 'text') {
     const content = msgType === 'text' ? JSON.stringify({ text }) : text;
     const res = await this._safeSDKCall(
@@ -419,7 +522,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.docx.document.create({ data: { title, folder_token: folderId || '' } }),
       label: 'createDoc',
     });
-    return { documentId: res.data.document?.document_id };
+    return { documentId: res.data.document?.document_id, viaUser: !!res._viaUser };
   }
 
   async getDocBlocks(documentId) {
@@ -499,7 +602,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.bitable.app.create({ data }),
       label: 'createBitable',
     });
-    return { appToken: res.data.app?.app_token, name: res.data.app?.name, url: res.data.app?.url };
+    return { appToken: res.data.app?.app_token, name: res.data.app?.name, url: res.data.app?.url, viaUser: !!res._viaUser };
   }
 
   async listBitableTables(appToken) {
@@ -785,7 +888,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.drive.file.createFolder({ data: body }),
       label: 'createFolder',
     });
-    return { token: res.data.token };
+    return { token: res.data.token, viaUser: !!res._viaUser };
   }
 
   // --- Drive: File Operations ---

package/src/utils.js

@@ -31,9 +31,22 @@ function formatCookie(cookieObj) {
     .join('; ');
 }
 
+// Wraps global fetch with an AbortController-based timeout. A stalled network
+// connection to feishu.cn can otherwise block an MCP tool handler indefinitely,
+// causing the client to time out and (in some clients) tear down the stdio
+// transport — observed as "MCP 中途掉线" by v1.3.2 users.
+// Default 30s; pass `timeoutMs` in init to override per-call.
+function fetchWithTimeout(url, init = {}) {
+  const { timeoutMs = 30000, ...rest } = init;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new Error(`fetch timeout after ${timeoutMs}ms: ${url}`)), timeoutMs);
+  return fetch(url, { ...rest, signal: rest.signal || controller.signal }).finally(() => clearTimeout(timer));
+}
+
 module.exports = {
   generateRequestId,
   generateCid,
   parseCookie,
   formatCookie,
+  fetchWithTimeout,
 };