feishu-user-plugin 1.3.4 → 1.3.6

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.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 -- 74 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 (74 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)
 
@@ -390,7 +392,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)
 
@@ -414,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 |
 |------|-------------|
@@ -429,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)
 
@@ -450,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 |
 |------|-------------|
@@ -459,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)
 
@@ -467,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/`:
@@ -508,10 +520,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 +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 (74 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.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.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/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.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 (74 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`)
@@ -32,7 +33,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 +53,11 @@ 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.
+- `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.
 - `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
@@ -125,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.
@@ -307,7 +325,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)
@@ -525,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,
 };