feishu-user-plugin 1.3.5 → 1.3.6

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "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.",
+  "version": "1.3.6",
+  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself (incl. batch_send and real @-mentions), read chats (auto-expanded merge_forward), manage docs (image + file blocks) / bitable (with attachment upload) / wiki / drive (file upload + wiki attach) / OKR / calendar / multi-profile. 81 tools + 9 skills, 3 auth layers. v1.3.6: upload completeness, sheets:spreadsheet scope, batch_send, multi-profile, send_card_as_user (bot-default).",
   "author": {
     "name": "EthanQC"
   },

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-74-orange.svg)](#tools)
+[![Tools](https://img.shields.io/badge/Tools-81-orange.svg)](#tools)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-**All-in-one Feishu/Lark MCP Server -- 75 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, OKR, and more.**
+**All-in-one Feishu/Lark MCP Server -- 81 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,9 +337,9 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 }
 ```
 
-## Tools (75 total)
+## Tools (81 total)
 
-### User Identity -- Messaging (8 tools, cookie auth)
+### User Identity -- Messaging (10 tools, cookie auth)
 
 | Tool | Description |
 |------|-------------|
@@ -351,6 +351,8 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 | `send_post_as_user` | Send rich text with title + formatted paragraphs |
 | `send_sticker_as_user` | Send sticker/emoji |
 | `send_audio_as_user` | Send audio message |
+| `batch_send` | Fan-out send to multiple targets in one call (text / image / file / post). v1.3.6 |
+| `send_card_as_user` | Send a Feishu interactive card. v1.3.6 default routes through bot identity; user-identity is reserved for v1.3.7. |
 
 ### User Identity -- Contacts & Info (5 tools, cookie auth)
 
@@ -415,11 +417,11 @@ All docx / bitable tools' `document_id` / `app_token` parameter also accepts a W
 | `read_doc` | Read raw text content |
 | `get_doc_blocks` | Get structured block tree |
 | `create_doc` | Create a new document |
-| `create_doc_block` | Insert content blocks into a document |
-| `update_doc_block` | Update a specific block |
+| `create_doc_block` | Insert content blocks: generic `children`, `image_path` / `image_token` (image block), `file_path` / `file_token` (file attachment block, v1.3.6) |
+| `update_doc_block` | Update a specific block: generic `update_body`, `image_token`, or `file_token` (v1.3.6) |
 | `delete_doc_blocks` | Delete a range of blocks |
 
-### Official API -- Bitable (17 tools)
+### Official API -- Bitable (18 tools)
 
 | Tool | Description |
 |------|-------------|
@@ -430,6 +432,7 @@ All docx / bitable tools' `document_id` / `app_token` parameter also accepts a W
 | `search_bitable_records` / `get_bitable_record` | Query records |
 | `create_bitable_record` / `update_bitable_record` / `delete_bitable_record` | Single record CRUD |
 | `batch_create_bitable_records` / `batch_update_bitable_records` / `batch_delete_bitable_records` | Batch operations (max 500/call) |
+| `upload_bitable_attachment` | Upload a file into a Bitable Attachment-type field. Returns `file_token` to write into the field as `[{file_token}]`. v1.3.6 |
 
 ### Official API -- Calendar (5 tools)
 
@@ -451,7 +454,7 @@ All docx / bitable tools' `document_id` / `app_token` parameter also accepts a W
 | `update_task` | Update a task |
 | `complete_task` | Mark task as complete |
 
-### Official API -- Drive (5 tools)
+### Official API -- Drive (6 tools)
 
 | Tool | Description |
 |------|-------------|
@@ -460,6 +463,7 @@ All docx / bitable tools' `document_id` / `app_token` parameter also accepts a W
 | `copy_file` | Copy a file |
 | `move_file` | Move a file |
 | `delete_file` | Delete a file/folder |
+| `upload_drive_file` | Upload a local file into a Drive folder (`drive/v1/files/upload_all`). Optional `wiki_space_id` attaches the upload as a Wiki node atomically. v1.3.6 |
 
 ### Official API -- Wiki & Contacts (4 tools)
 
@@ -468,6 +472,13 @@ All docx / bitable tools' `document_id` / `app_token` parameter also accepts a W
 | `list_wiki_spaces` / `search_wiki` / `list_wiki_nodes` | Wiki spaces, search, browse |
 | `find_user` | Find user by email or mobile number |
 
+### Plugin -- Profiles (2 tools, v1.3.6)
+
+| Tool | Description |
+|------|-------------|
+| `list_profiles` | List available identity profiles (default + extras from `LARK_PROFILES_JSON`) and the active one |
+| `switch_profile` | Hot-swap active profile; cached client instances rebuild against new credentials |
+
 ## Claude Code Slash Commands (9 skills)
 
 This plugin includes 9 built-in skills in `skills/feishu-user-plugin/`:
@@ -526,7 +537,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 (75 tools)
+│   ├── index.js             # MCP server entry point (81 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.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.",
+  "version": "1.3.6",
+  "description": "All-in-one Feishu plugin for Claude Code & Codex — messaging (with merge_forward expansion + batch_send), docs (image + file blocks read/write), bitable (with attachment upload), wiki, drive (file upload + wiki attach), OKR, calendar, multi-profile. 81 tools + 9 skills, 3 auth layers. v1.3.6: upload completeness, sheets:spreadsheet scope, batch_send, multi-profile, send_card_as_user (bot-default).",
   "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.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
+version: "1.3.6"
+description: "All-in-one Feishu plugin — send messages as yourself (incl. batch_send), read group/P2P chats (auto-expands merge_forward), manage docs/tables/wiki/drive (image + file blocks, drive uploads, bitable attachments), OKR, calendar, multi-profile. v1.3.6: upload completeness, sheets:spreadsheet scope, batch_send, multi-profile, send_card_as_user (bot-default)."
+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, batch_send, send_card_as_user, search_contacts, create_p2p_chat, get_chat_info, get_user_info, get_login_status, list_profiles, switch_profile, read_p2p_messages, list_user_chats, list_chats, read_messages, reply_message, forward_message, search_docs, read_doc, create_doc, create_doc_block, update_doc_block, list_bitable_tables, list_bitable_fields, search_bitable_records, batch_create_bitable_records, batch_update_bitable_records, upload_bitable_attachment, list_wiki_spaces, search_wiki, list_wiki_nodes, get_wiki_node, list_files, create_folder, upload_drive_file, 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,11 +6,12 @@ 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 (75 tools)
+## Tool Categories (81 tools)
 
 ### User Identity — Messaging (reverse-engineered, cookie-based)
 - `send_to_user` — Search user + send text (one step, most common). Returns candidates if multiple matches.
 - `send_to_group` — Search group + send text (one step). Returns candidates if multiple matches.
+- `batch_send` — Fan-out send to multiple targets in one call (text/image/file/post). Each target {type, id, content, via?} dispatches sequentially with throttling, returns per-target ok/error.
 - `send_as_user` — Send text to any chat by ID, supports reply threading (root_id/parent_id)
 - `send_image_as_user` — Send image (requires image_key from `upload_image`)
 - `send_file_as_user` — Send file (requires file_key from `upload_file`)
@@ -52,6 +53,9 @@ 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
+- `upload_drive_file` — Upload a local file into a Drive folder (`drive/v1/files/upload_all`, `parent_type=explorer`). Returns `file_token` + `url`. If `wiki_space_id` is provided, the upload is followed by `attachToWiki(obj_type=file)` so the file lands as a Wiki node atomically. UAT-first with bot fallback.
+- `upload_bitable_attachment` — Upload a local file as a Bitable attachment (`drive/v1/medias/upload_all` with `parent_type=bitable_image` or `bitable_file`). Returns `file_token` to write into an Attachment-type field via `batch_create/update_bitable_records` as `[{file_token: "..."}]`.
+- `send_card_as_user` — Send a Feishu interactive card. **v1.3.6 default routes through bot identity** (the `as_user` suffix is reserved for the v1.3.7 reverse-engineered cookie path; default flips when that lands). Pass `card` JSON; `via="user"` returns an explicit deferred error in v1.3.6.
 - `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.
@@ -126,10 +130,23 @@ Write — `create_doc_block` now has image shortcuts:
 - Create doc with content → `create_doc` → `create_doc_block` (use document_id as parent_block_id for root)
 - Edit existing block → `get_doc_blocks` to find block_id → `update_doc_block`
 - Delete blocks → `delete_doc_blocks` with start/end index range
+- Insert image → `create_doc_block` with `image_path` (local file) or `image_token` (already uploaded). Three-step flow handled internally.
+- Insert file attachment (PDF/zip/xlsx/...) → `create_doc_block` with `file_path` or `file_token`. Feishu auto-wraps the FILE block (block_type=23) inside a VIEW container (block_type=33); the plugin walks into the inner file block automatically before the `replace_file` PATCH so the upload + attach succeed.
+- Replace existing image/file in a block → `update_doc_block` with `image_token` / `file_token`.
 
 ### Diagnostics
 - Diagnose issues → `get_login_status` first
 
+### Profiles (v1.3.6)
+Multi-account / multi-tenant support without restarting the MCP server:
+- `list_profiles` — see all profiles + the active one. Default profile uses top-level env vars; extras come from `LARK_PROFILES_JSON`.
+- `switch_profile(name)` — hot-swap credentials. Cached client instances are invalidated so the next call rebuilds against the new profile.
+
+To register more profiles, set `LARK_PROFILES_JSON` in the MCP env:
+```json
+{"alt": {"LARK_COOKIE":"...","LARK_APP_ID":"...","LARK_APP_SECRET":"...","LARK_USER_ACCESS_TOKEN":"...","LARK_USER_REFRESH_TOKEN":"..."}}
+```
+
 ## Auth & Session
 - **LARK_COOKIE**: Required for user identity tools. Session auto-refreshed every 4h via heartbeat and persisted to config.
 - **LARK_APP_ID + LARK_APP_SECRET**: Required for official API tools.
@@ -541,10 +558,10 @@ The v1.3.4 tools require additional scopes on the app + UAT:
 |---------|-------------------------------------------|
 | OKR read | `okr:okr:readonly`, `okr:period:read` |
 | Calendar read | `calendar:calendar:readonly`, `calendar:calendar.event:read` |
-| Docx image write (`uploadDocMedia`) | `drive:drive`, `docx:document`, `docx:document:readonly` (image upload piggy-backs on existing docx editing scopes) |
+| Docx/Bitable/Drive media upload (`uploadMedia`, `upload_drive_file`, `upload_bitable_attachment`, `create_doc_block` image/file) | `drive:drive`, `drive:file:upload`, `docs:document.media:upload`, `sheets:spreadsheet` (only for sheet uploads) |
 | Wiki attach (`move_docs_to_wiki`) | `wiki:wiki` (edit scope, the readonly one is insufficient) |
 
-If a tool returns `access_denied` or error code `99991672` (scope not granted), enable the missing scope at https://open.feishu.cn/app → Permissions, then re-run `npx feishu-user-plugin oauth` so the UAT picks up the new scopes.
+If a tool returns `access_denied` or error code `99991672` (scope not granted), the scope is missing on either the app or the UAT. Re-run `npx feishu-user-plugin oauth` so the UAT picks up the latest scope list (defined in `src/oauth.js`).
 
 ## Known Limitations
 - CARD message type (type=14) not yet implemented — complex JSON schema

package/src/doc-blocks.js

@@ -1,10 +1,8 @@
 // Helpers for constructing docx block payloads.
 //
-// Right now (v1.3.4) only the image path is implemented — enough to cover the
-// create_doc_block / update_doc_block image shortcuts. More block builders
-// (heading / list / code / table) will land in v1.3.5 when the local-markdown
-// → wiki-docx sync feature is built; parking the skeleton here now so the
-// later additions don't introduce a new file.
+// v1.3.4 added image block builders. v1.3.6 adds file block builders so the
+// create_doc_block / update_doc_block tools can attach arbitrary file
+// attachments (PDF / zip / etc.) the same way they handle images.
 
 // docx v1 block_type enum (relevant subset).
 // Docs: https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document-block/create
@@ -63,8 +61,25 @@ function buildReplaceImagePayload(imageToken) {
   return { replace_image: { token: imageToken } };
 }
 
+// File-block flow mirrors the image-block flow but uses block_type=23 (FILE)
+// and parent_type=docx_file when uploading the binary, and replace_file in
+// the PATCH body. See official.js::createDocBlockWithFile.
+
+/** Empty file block placeholder for step 1 of file attachment flow. */
+function buildEmptyFileBlock() {
+  return { block_type: BLOCK_TYPE.FILE, file: {} };
+}
+
+/** Patch body that swaps an empty file block's content with an uploaded file token. */
+function buildReplaceFilePayload(fileToken) {
+  if (!fileToken) throw new Error('buildReplaceFilePayload: fileToken is required');
+  return { replace_file: { token: fileToken } };
+}
+
 module.exports = {
   BLOCK_TYPE,
   buildEmptyImageBlock,
   buildReplaceImagePayload,
+  buildEmptyFileBlock,
+  buildReplaceFilePayload,
 };

package/src/index.js

@@ -113,17 +113,53 @@ class ChatIdMapper {
   }
 }
 
-// --- Client Singletons ---
+// --- Client Singletons + Profiles ---
 
 let userClient = null;
 let officialClient = null;
 const chatIdMapper = new ChatIdMapper();
 
+// Profile system (v1.3.6).
+// Default behaviour is identical to pre-1.3.6: LARK_COOKIE / LARK_APP_ID / etc.
+// from process.env act as profile "default". To register more profiles, set
+// LARK_PROFILES_JSON in the MCP env to a JSON object:
+//   { "alt": { "LARK_COOKIE": "...", "LARK_APP_ID": "...", ... }, ... }
+// Then call switch_profile to change which credential set is active.
+let currentProfile = 'default';
+
+function loadProfileMap() {
+  const raw = process.env.LARK_PROFILES_JSON;
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object') return parsed;
+  } catch (e) {
+    console.error(`[feishu-user-plugin] LARK_PROFILES_JSON parse failed: ${e.message}`);
+  }
+  return {};
+}
+
+function profileEnv(name) {
+  if (name === 'default') {
+    return {
+      LARK_COOKIE: process.env.LARK_COOKIE,
+      LARK_APP_ID: process.env.LARK_APP_ID,
+      LARK_APP_SECRET: process.env.LARK_APP_SECRET,
+      LARK_USER_ACCESS_TOKEN: process.env.LARK_USER_ACCESS_TOKEN,
+      LARK_USER_REFRESH_TOKEN: process.env.LARK_USER_REFRESH_TOKEN,
+    };
+  }
+  const profiles = loadProfileMap();
+  if (!profiles[name]) throw new Error(`Profile "${name}" not found. Available: ${['default', ...Object.keys(profiles)].join(', ')}`);
+  return profiles[name];
+}
+
 async function getUserClient() {
   if (userClient) return userClient;
-  const cookie = process.env.LARK_COOKIE;
+  const env = profileEnv(currentProfile);
+  const cookie = env.LARK_COOKIE;
   if (!cookie) throw new Error(
-    'LARK_COOKIE not set. To fix:\n' +
+    `LARK_COOKIE not set for profile "${currentProfile}". To fix:\n` +
     '1. Open https://www.feishu.cn/messenger/ and log in\n' +
     '2. DevTools → Network tab → Disable cache → Reload → Click first request → Request Headers → Cookie → Copy value\n' +
     '   (Do NOT use document.cookie or Application→Cookies — they miss HttpOnly cookies like session/sl_session)\n' +
@@ -137,21 +173,52 @@ async function getUserClient() {
 
 function getOfficialClient() {
   if (officialClient) return officialClient;
-  const appId = process.env.LARK_APP_ID;
-  const appSecret = process.env.LARK_APP_SECRET;
+  const env = profileEnv(currentProfile);
+  const appId = env.LARK_APP_ID;
+  const appSecret = env.LARK_APP_SECRET;
   if (!appId || !appSecret) throw new Error(
-    'LARK_APP_ID and LARK_APP_SECRET not set.\n' +
+    `LARK_APP_ID and LARK_APP_SECRET not set for profile "${currentProfile}".\n` +
     'For team members: these should be pre-filled in your .mcp.json. Check that the config was copied correctly from the team-skills README.\n' +
     'For external users: create a Custom App at https://open.feishu.cn/app, get the App ID and App Secret, add them to your .mcp.json env.'
   );
+  // Honor profile-specific UAT env if present (LarkOfficialClient.loadUAT uses
+  // process.env directly; we patch the env temporarily for non-default profiles)
+  const prevUAT = process.env.LARK_USER_ACCESS_TOKEN;
+  const prevRT = process.env.LARK_USER_REFRESH_TOKEN;
+  if (currentProfile !== 'default') {
+    if (env.LARK_USER_ACCESS_TOKEN) process.env.LARK_USER_ACCESS_TOKEN = env.LARK_USER_ACCESS_TOKEN;
+    if (env.LARK_USER_REFRESH_TOKEN) process.env.LARK_USER_REFRESH_TOKEN = env.LARK_USER_REFRESH_TOKEN;
+  }
   officialClient = new LarkOfficialClient(appId, appSecret);
   officialClient.loadUAT();
+  if (currentProfile !== 'default') {
+    process.env.LARK_USER_ACCESS_TOKEN = prevUAT;
+    process.env.LARK_USER_REFRESH_TOKEN = prevRT;
+  }
   return officialClient;
 }
 
 // --- Tool Definitions ---
 
 const TOOLS = [
+  // ========== Profile management (v1.3.6) ==========
+  {
+    name: 'list_profiles',
+    description: '[Plugin] List all available identity profiles (sets of LARK_COOKIE/APP_ID/APP_SECRET/UAT). The "default" profile uses the top-level env vars; additional profiles come from LARK_PROFILES_JSON. Marks the currently active profile.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'switch_profile',
+    description: '[Plugin] Switch the active identity profile. Subsequent tool calls use the new profile\'s credentials. Cached client instances are reset so the next call rebuilds against the new creds.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Profile name. "default" for top-level env vars; any key from LARK_PROFILES_JSON otherwise.' },
+      },
+      required: ['name'],
+    },
+  },
+
   // ========== User Identity — Send Messages ==========
   {
     name: 'send_as_user',
@@ -206,6 +273,22 @@ const TOOLS = [
       required: ['group_name', 'text'],
     },
   },
+  {
+    name: 'batch_send',
+    description: '[User Identity / Official API] Send the same or different content to multiple targets in one call. Each target dispatches sequentially with a small delay (anti-rate-limit) and reports per-target success/error. Identity is the cookie user (user-identity sends) unless target.via=bot. Use for broadcast / fan-out scenarios.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        targets: {
+          type: 'array',
+          description: 'Array of targets. Each entry: { type: "user"|"group"|"chat", id: <user_name | group_name | chat_id>, content: { kind: "text"|"image"|"file"|"post", ... } }. For kind="text": { text }. For "image": { image_key }. For "file": { file_key, file_name }. For "post": { title, paragraphs }. Optional per-target: via="bot" routes through send_message_as_bot (chat_id required).',
+          items: { type: 'object' },
+        },
+        delay_ms: { type: 'number', description: 'Delay between sends in milliseconds (default 200, increase for risky volumes).' },
+      },
+      required: ['targets'],
+    },
+  },
   {
     name: 'send_image_as_user',
     description: '[User Identity] Send an image as the logged-in user. Requires image_key (upload via Official API first).',
@@ -689,6 +772,33 @@ const TOOLS = [
       required: ['file_path'],
     },
   },
+  {
+    name: 'upload_drive_file',
+    description: '[Official API] Upload a file from disk to a Feishu Drive folder (drive/v1/files/upload_all, parent_type=explorer). Returns file_token + url. If wiki_space_id is provided, the uploaded file is then attached to that Wiki space via move_docs_to_wiki (obj_type=file). UAT-first with app fallback.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the file on disk' },
+        folder_token: { type: 'string', description: 'Destination folder token. Use list_files to find one, or pass the user "我的空间" root token.' },
+        wiki_space_id: { type: 'string', description: 'Optional. If set, also attach the uploaded file to this Wiki space.' },
+        wiki_parent_node_token: { type: 'string', description: 'Optional. Parent node under which to attach in the Wiki space.' },
+      },
+      required: ['file_path', 'folder_token'],
+    },
+  },
+  {
+    name: 'upload_bitable_attachment',
+    description: '[Official API] Upload a file as a Bitable attachment (drive/v1/medias/upload_all with parent_type=bitable_image or bitable_file). Returns file_token suitable for writing into a Bitable Attachment-type field via batch_create/update_bitable_records (the field value should be [{file_token}]).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        app_token: { type: 'string', description: 'Bitable app token (the bascn... or basc... id)' },
+        file_path: { type: 'string', description: 'Absolute path to the file on disk' },
+        kind: { type: 'string', enum: ['image', 'file'], description: 'Whether the attachment is an image (bitable_image) or a generic file (bitable_file). Default: file.' },
+      },
+      required: ['app_token', 'file_path'],
+    },
+  },
 
   // ========== Contact — Official API ==========
   {
@@ -717,6 +827,19 @@ const TOOLS = [
       required: ['chat_id', 'msg_type', 'content'],
     },
   },
+  {
+    name: 'send_card_as_user',
+    description: '[v1.3.6: bot-routed default] Send an interactive card to a chat. **As of v1.3.6, identity defaults to BOT** because user-identity card sending requires reverse-engineering the Feishu web protobuf and is deferred to v1.3.7. The tool name keeps the "as_user" suffix so callers don\'t have to migrate when v1.3.7 lands; once user-identity is implemented the default flips. Pass `card` as a JSON object (Feishu card schema). To force bot explicitly set via="bot".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: 'Target chat_id (oc_xxx) or open_id' },
+        card: { description: 'Feishu card JSON. See https://open.feishu.cn/cardkit for the schema; build cards visually then paste the resulting JSON here.' },
+        via: { type: 'string', enum: ['bot', 'user'], description: 'Identity to send as. Default "bot". "user" returns an explicit not-yet-implemented error in v1.3.6.' },
+      },
+      required: ['chat_id', 'card'],
+    },
+  },
   {
     name: 'delete_message',
     description: '[Official API] Recall/delete a message (bot can only delete its own messages).',
@@ -837,15 +960,17 @@ const TOOLS = [
   // ========== Docs — Block Editing ==========
   {
     name: 'create_doc_block',
-    description: '[Official API] Insert content blocks into a document. Three modes:\n  (A) Generic — pass `children` array (e.g. [{block_type:2, text:{...}}]) for text/heading/list/etc.\n  (B) Image from local file — pass `image_path` (absolute path); the plugin creates an image block, uploads the file to drive, and patches the block with the token. Returns block_id + image_token.\n  (C) Image from uploaded token — pass `image_token` (from a previous uploadDocMedia or docx image block) to reuse an already-uploaded image.\n`document_id` accepts native document_id, wiki node token, or Feishu URL.',
+    description: '[Official API] Insert content blocks into a document. Five modes:\n  (A) Generic — pass `children` array (e.g. [{block_type:2, text:{...}}]) for text/heading/list/etc.\n  (B) Image from local file — pass `image_path` (absolute path); the plugin creates an image block, uploads the file to drive, and patches the block with the token. Returns block_id + image_token.\n  (C) Image from uploaded token — pass `image_token` to reuse an already-uploaded image.\n  (D) File attachment from local file — pass `file_path`; the plugin creates a file block (block_type=23), uploads via parent_type=docx_file, and patches with replace_file.\n  (E) File from uploaded token — pass `file_token` to reuse an already-uploaded file.\n`document_id` accepts native document_id, wiki node token, or Feishu URL.',
     inputSchema: {
       type: 'object',
       properties: {
         document_id: { type: 'string', description: 'Document ID, wiki node token, or Feishu URL' },
         parent_block_id: { type: 'string', description: 'Parent block ID (use document_id for root)' },
         children: { type: 'array', description: 'Generic block objects — mode A. E.g. [{block_type:2, text:{elements:[{text_run:{content:"Hello"}}]}}]', items: { type: 'object' } },
-        image_path: { type: 'string', description: 'Local image path — mode B (mutually exclusive with children / image_token)' },
-        image_token: { type: 'string', description: 'Pre-uploaded docx image token — mode C (mutually exclusive with children / image_path)' },
+        image_path: { type: 'string', description: 'Local image path — mode B (mutually exclusive with other modes)' },
+        image_token: { type: 'string', description: 'Pre-uploaded docx image token — mode C (mutually exclusive with other modes)' },
+        file_path: { type: 'string', description: 'Local file path for an attachment block — mode D (mutually exclusive with other modes)' },
+        file_token: { type: 'string', description: 'Pre-uploaded docx file token — mode E (mutually exclusive with other modes)' },
         index: { type: 'number', description: 'Insert position (optional, appends to end if omitted)' },
       },
       required: ['document_id', 'parent_block_id'],
@@ -853,7 +978,7 @@ const TOOLS = [
   },
   {
     name: 'update_doc_block',
-    description: '[Official API] Update a specific block in a document. Generic mode: pass update_body. Image-replace mode: pass image_token to swap the picture in an existing image block. document_id accepts native ID, wiki node token, or Feishu URL.',
+    description: '[Official API] Update a specific block in a document. Generic mode: pass update_body. Image-replace mode: pass image_token to swap the picture in an existing image block. File-replace mode: pass file_token to swap an existing file block. document_id accepts native ID, wiki node token, or Feishu URL.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -861,6 +986,7 @@ const TOOLS = [
         block_id: { type: 'string', description: 'Block ID to update' },
         update_body: { type: 'object', description: 'Generic update payload. E.g. {update_text_elements:{elements:[{text_run:{content:"new text"}}]}}' },
         image_token: { type: 'string', description: 'Pre-uploaded image token — if provided, update_body is ignored and the block is patched with {replace_image:{token}}' },
+        file_token: { type: 'string', description: 'Pre-uploaded file token — patches the block with {replace_file:{token}}' },
       },
       required: ['document_id', 'block_id'],
     },
@@ -1177,6 +1303,25 @@ async function resolveDocId(input) {
 async function handleTool(name, args) {
 
   switch (name) {
+    // --- Profile management (v1.3.6) ---
+
+    case 'list_profiles': {
+      const profiles = loadProfileMap();
+      const all = ['default', ...Object.keys(profiles)];
+      return json({ active: currentProfile, profiles: all });
+    }
+    case 'switch_profile': {
+      const target = args.name;
+      const profiles = loadProfileMap();
+      const all = ['default', ...Object.keys(profiles)];
+      if (!all.includes(target)) return text(`Profile "${target}" not found. Available: ${all.join(', ')}. To add more, set LARK_PROFILES_JSON in your MCP env.`);
+      currentProfile = target;
+      // Invalidate cached client instances so the next call uses the new creds
+      userClient = null;
+      officialClient = null;
+      return text(`Switched to profile: ${target}`);
+    }
+
     // --- User Identity: Text Messaging ---
 
     case 'send_as_user': {
@@ -1212,6 +1357,56 @@ async function handleTool(name, args) {
       const r = await c.sendMessage(group.id, args.text, { ats: args.ats });
       return sendResult(r, `Text sent to group "${group.title}" (${group.id})`);
     }
+    case 'batch_send': {
+      if (!Array.isArray(args.targets) || args.targets.length === 0) return text('batch_send: targets must be a non-empty array');
+      const delay = typeof args.delay_ms === 'number' ? args.delay_ms : 200;
+      const userClient = await getUserClient();
+      const officialClient = getOfficialClient();
+      const results = [];
+      for (let i = 0; i < args.targets.length; i++) {
+        const t = args.targets[i];
+        try {
+          if (!t.content || !t.content.kind) throw new Error('content.kind is required');
+          // Resolve chat id from name when applicable
+          let chatId = t.id;
+          if (t.type === 'user' || t.type === 'group') {
+            const matches = await userClient.search(t.id);
+            const want = matches.filter(m => m.type === t.type);
+            if (want.length === 0) throw new Error(`No ${t.type} matches "${t.id}"`);
+            if (want.length > 1) throw new Error(`Ambiguous ${t.type} "${t.id}" (${want.length} matches). Use type="chat" with explicit chat_id.`);
+            const picked = want[0];
+            chatId = t.type === 'user' ? await userClient.createChat(picked.id) : picked.id;
+            if (!chatId) throw new Error(`Could not resolve chat for ${t.type} ${picked.title}`);
+          }
+          let r;
+          if (t.via === 'bot') {
+            const c = t.content;
+            const payload = c.kind === 'text' ? { text: c.text }
+              : c.kind === 'post' ? { post: { zh_cn: { title: c.title || '', content: c.paragraphs || [] } } }
+              : c.kind === 'image' ? { image_key: c.image_key }
+              : c.kind === 'interactive' ? c.card
+              : null;
+            if (!payload) throw new Error(`bot path does not support content.kind=${c.kind}`);
+            const msgType = c.kind === 'interactive' ? 'interactive' : c.kind;
+            r = await officialClient.sendMessageAsBot(chatId, msgType, payload);
+            results.push({ ok: true, target: t, messageId: r.messageId, via: 'bot' });
+          } else {
+            const c = t.content;
+            if (c.kind === 'text') r = await userClient.sendMessage(chatId, c.text, { ats: c.ats });
+            else if (c.kind === 'image') r = await userClient.sendImage(chatId, c.image_key);
+            else if (c.kind === 'file') r = await userClient.sendFile(chatId, c.file_key, c.file_name);
+            else if (c.kind === 'post') r = await userClient.sendPost(chatId, c.title, c.paragraphs);
+            else throw new Error(`unknown content.kind=${c.kind}`);
+            results.push({ ok: true, target: t, messageId: r.messageId, via: 'user' });
+          }
+        } catch (e) {
+          results.push({ ok: false, target: t, error: e.message });
+        }
+        if (i < args.targets.length - 1 && delay > 0) await new Promise(r => setTimeout(r, delay));
+      }
+      const okCount = results.filter(r => r.ok).length;
+      return json({ summary: `${okCount}/${results.length} sent`, results });
+    }
 
     // --- User Identity: Rich Message Types ---
 
@@ -1510,9 +1705,38 @@ async function handleTool(name, args) {
       const r = await getOfficialClient().uploadFile(args.file_path, args.file_type, args.file_name);
       return text(`File uploaded: ${r.fileKey}\nUse this file_key with send_file_as_user to send it.`);
     }
+    case 'upload_drive_file': {
+      const official = getOfficialClient();
+      const up = await official.uploadDriveFile(args.file_path, args.folder_token);
+      const out = { fileToken: up.fileToken, viaUser: up.viaUser, url: `https://feishu.cn/file/${up.fileToken}` };
+      if (args.wiki_space_id) {
+        try {
+          const node = await official.attachToWiki(args.wiki_space_id, 'file', up.fileToken, args.wiki_parent_node_token);
+          out.wikiNodeToken = node.node_token || null;
+          out.wikiAttachTaskId = node.task_id || null;
+        } catch (e) {
+          out.wikiAttachError = e.message;
+        }
+      }
+      return json(out);
+    }
+    case 'upload_bitable_attachment': {
+      const kind = args.kind === 'image' ? 'bitable_image' : 'bitable_file';
+      const appToken = await resolveDocId(args.app_token);
+      const up = await getOfficialClient().uploadMedia(args.file_path, appToken, kind);
+      return json({ fileToken: up.fileToken, viaUser: up.viaUser, parentType: kind, hint: `Pass [{ file_token: "${up.fileToken}" }] as the value of an Attachment-type Bitable field.` });
+    }
 
     // --- Official API: Bot Send / Edit / Delete ---
 
+    case 'send_card_as_user': {
+      const via = args.via || 'bot';
+      if (via === 'user') {
+        return text('send_card_as_user via="user" is not implemented in v1.3.6 — user-identity card sending requires reverse-engineering the Feishu web protobuf and is scheduled for v1.3.7. Use via="bot" (default) for now.');
+      }
+      const r = await getOfficialClient().sendMessageAsBot(args.chat_id, 'interactive', args.card);
+      return text(`Card sent (${via}): ${r.messageId}`);
+    }
     case 'send_message_as_bot': {
       const r = await getOfficialClient().sendMessageAsBot(args.chat_id, args.msg_type, args.content);
       return text(`Message sent (bot): ${r.messageId}`);
@@ -1555,10 +1779,9 @@ async function handleTool(name, args) {
     case 'create_doc_block': {
       const official = getOfficialClient();
       const docId = await resolveDocId(args.document_id);
-      // Image shortcut: if image_path or image_token is provided, orchestrate the
-      // 3-step docx image creation. Mutually exclusive with children.
+      const modes = [args.children, args.image_path, args.image_token, args.file_path, args.file_token].filter(Boolean);
+      if (modes.length > 1) return text('create_doc_block: pass exactly ONE of children / image_path / image_token / file_path / file_token.');
       if (args.image_path || args.image_token) {
-        if (args.children) return text('create_doc_block: pass children OR image_path OR image_token, not both.');
         const r = await official.createDocBlockWithImage(docId, args.parent_block_id, {
           imagePath: args.image_path,
           imageToken: args.image_token,
@@ -1566,19 +1789,29 @@ async function handleTool(name, args) {
         });
         return json(r);
       }
-      if (!args.children) return text('create_doc_block: children (generic blocks), image_path, or image_token is required.');
+      if (args.file_path || args.file_token) {
+        const r = await official.createDocBlockWithFile(docId, args.parent_block_id, {
+          filePath: args.file_path,
+          fileToken: args.file_token,
+          index: args.index,
+        });
+        return json(r);
+      }
+      if (!args.children) return text('create_doc_block: children, image_path, image_token, file_path, or file_token is required.');
       return json(await official.createDocBlock(docId, args.parent_block_id, args.children, args.index));
     }
     case 'update_doc_block': {
       const official = getOfficialClient();
       const docId = await resolveDocId(args.document_id);
-      if (args.image_token && args.update_body) {
-        return text('update_doc_block: pass image_token OR update_body, not both.');
-      }
+      const modes = [args.update_body, args.image_token, args.file_token].filter(Boolean);
+      if (modes.length > 1) return text('update_doc_block: pass exactly ONE of update_body / image_token / file_token.');
       if (args.image_token) {
         return json(await official.updateDocBlockImage(docId, args.block_id, args.image_token));
       }
-      if (!args.update_body) return text('update_doc_block: update_body or image_token is required.');
+      if (args.file_token) {
+        return json(await official.updateDocBlockFile(docId, args.block_id, args.file_token));
+      }
+      if (!args.update_body) return text('update_doc_block: update_body, image_token, or file_token is required.');
       return json(await official.updateDocBlock(docId, args.block_id, args.update_body));
     }
     case 'delete_doc_blocks':

package/src/oauth.js

@@ -28,7 +28,10 @@ const REDIRECT_URI = `http://127.0.0.1:${PORT}/callback`;
 //   calendar:*                             for list_calendars / list_calendar_events / get_calendar_event
 //   wiki:wiki                              write access for move_docs_to_wiki (attach docs/bitables to wiki)
 //   docs:document.media:(upload|download)  for docx image read/write
-const SCOPES = 'offline_access auth:user.id:read im:message im:message:readonly im:chat im:chat:readonly contact:user.base:readonly contact:user.id:readonly docx:document drive:drive bitable:app wiki:wiki:readonly wiki:wiki okr:okr:readonly okr:okr.period:readonly okr:okr.content:readonly calendar:calendar:readonly calendar:calendar.event:read docs:document.media:download docs:document.media:upload';
+// v1.3.6 additions:
+//   sheets:spreadsheet                     for sheet_image / sheet_file media uploads
+//   drive:file:upload                      narrower scope for drive/v1/files/upload_all (independent of drive:drive)
+const SCOPES = 'offline_access auth:user.id:read im:message im:message:readonly im:chat im:chat:readonly contact:user.base:readonly contact:user.id:readonly docx:document drive:drive drive:file:upload bitable:app wiki:wiki:readonly wiki:wiki okr:okr:readonly okr:okr.period:readonly okr:okr.content:readonly calendar:calendar:readonly calendar:calendar.event:read docs:document.media:download docs:document.media:upload sheets:spreadsheet';
 
 if (!APP_ID || !APP_SECRET) {
   console.error('Missing LARK_APP_ID or LARK_APP_SECRET.');

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
@@ -1447,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);
@@ -1465,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';
 
@@ -1490,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 };
   }
@@ -1544,7 +1635,7 @@ class LarkOfficialClient {
     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
     }
@@ -1567,7 +1658,7 @@ class LarkOfficialClient {
 
   // 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({
@@ -1583,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