feishu-user-plugin 1.3.3 → 1.3.5

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.4] - 2026-04-22
+
+### Added
+- **Wiki-hosted content is now first-class**: every docx and bitable tool accepts the `document_id` / `app_token` parameter in three forms — native token (unchanged), wiki node token (`wikcnXXX` / `wikmXXX` / `wiknXXX`), or a full Feishu URL (`https://xxx.feishu.cn/docx/XXX`, `.../wiki/XXX`, `.../base/XXX`). A new `src/resolver.js` parses the input, calls `wiki/v2/spaces/get_node` when needed to resolve to `obj_token` + `obj_type`, and caches the mapping for 10 min. Zero-lookup path for direct URLs.
+- **`get_wiki_node` tool**: explicitly resolves a Wiki node to its backing object (`obj_type` + `obj_token` + `space_id`). Useful when you need to branch behaviour on whether a node points at a docx, bitable, sheet, mindnote, file, or slides.
+- **Create docx / bitable directly under Wiki**: `create_doc` / `create_bitable` accept optional `wiki_space_id` (and `wiki_parent_node_token` for nested placement). Plugin creates the resource in drive, then calls `wiki/v2/spaces/{space_id}/nodes/move_docs_to_wiki` to attach it. Returns `wikiNodeToken` on success, `wikiAttachTaskId` when Feishu queues the move, or a warning if attach fails (resource still in drive).
+- **Docx image read**: `download_image` now has a docx mode — pass `image_token` (from `get_doc_blocks` image block) and optional `doc_token` (native / wiki node / URL). Routes through `drive/v1/medias/{token}/download`, returns base64 as MCP image content so the model sees the pixels.
+- **Docx image write**: `create_doc_block` gains two shortcut parameters — `image_path` (local file) automatically runs the three-step Feishu flow (create empty image block → upload via `drive/v1/medias/upload_all` with `parent_type=docx_image` and the new block_id → patch with `replace_image`); `image_token` reuses an already-uploaded media token. `update_doc_block` accepts `image_token` to swap the picture in an existing image block.
+- **`list_user_okrs` / `get_okrs` / `list_okr_periods` tools**: read a user's OKRs, batch fetch full objective + key result details (progress, alignments, mentions), and enumerate periods. UAT-first with app fallback when the OKR scope is granted.
+- **`list_calendars` / `list_calendar_events` / `get_calendar_event` tools**: list the user's calendars (primary / shared / subscribed), list events in a time window, and fetch full event details (attendees, location, meeting links, attachments).
+
+### Fixed
+- **External-group `read_messages` hardening**: new `src/error-codes.js` classifies bot failures. Known-needs-UAT codes (`240001` external tenant, `70009` no permission, `70003` / `99991668` bot not in chat, `19001` chat not found) hop straight to UAT. Transient codes (`42101` rate limit, `5xx`, `ECONNRESET`, fetch timeouts) retry once after a 2 s delay before falling back. Response now includes `via: "bot" | "user" | "contacts"` and, when fallback fires, `via_reason` (e.g. `bot_external_tenant`). When the `chat_id` was discovered via `search_contacts` (i.e. definitely external) the bot path is skipped entirely.
+- **Raw Feishu payload no longer leaks when UAT is missing**: bot failures with no UAT configured now produce `Cannot read chat <id> as bot (<reason>). To read external/private groups, configure UAT via: npx feishu-user-plugin oauth` — previously the caller got the unwrapped Feishu error JSON.
+- **`_uatREST` array query params**: OKR / calendar endpoints that take repeated query keys (e.g. `period_ids=p1&period_ids=p2`) now serialize correctly. Previously `URLSearchParams(query)` would call `toString` on arrays and produce CSV, which Feishu rejects.
+
+### Changed
+- Tool count 67 → **74** (+7: `get_wiki_node`, `list_user_okrs`, `get_okrs`, `list_okr_periods`, `list_calendars`, `list_calendar_events`, `get_calendar_event`).
+- `getWikiNode(nodeToken, _spaceId)` — `spaceId` parameter position swapped; retained only for backward-compatibility of any external caller. The endpoint itself ignores `space_id`.
+- `create_doc_block` no longer requires `children` — callers who use the new `image_path` or `image_token` shortcut omit it. One of `children` / `image_path` / `image_token` must be provided.
+
 ## [1.3.3] - 2026-04-20
 
 ### 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-67-orange.svg)](#tools)
+[![Tools](https://img.shields.io/badge/Tools-74-orange.svg)](#tools)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-**All-in-one Feishu/Lark MCP Server -- 67 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, and more.**
+**All-in-one Feishu/Lark MCP Server -- 75 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, OKR, and more.**
 
 The only MCP server that lets you send messages as your **personal identity** (not a bot), while also integrating the full official Feishu API. Works with Claude Code, Cursor, Windsurf, OpenClaw, and any MCP-compatible client.
 
@@ -337,7 +337,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 }
 ```
 
-## Tools (67 total)
+## Tools (75 total)
 
 ### User Identity -- Messaging (8 tools, cookie auth)
 
@@ -390,7 +390,22 @@ 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 |
+| `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)
+
+| Tool | Description |
+|------|-------------|
+| `get_wiki_node` | Resolve a Wiki node token to its underlying obj_type + obj_token + space_id |
+| `list_user_okrs` | List a user's OKRs (requires open_id; filter by period_ids) |
+| `get_okrs` | Batch-fetch full OKR details (objectives, key results, progress, alignments) |
+| `list_okr_periods` | List OKR periods (quarters / years) |
+| `list_calendars` | List the current user's calendars (primary + shared + subscribed) |
+| `list_calendar_events` | List events in a calendar within a time range |
+| `get_calendar_event` | Full event details (attendees, location, meeting link, attachments) |
+
+All docx / bitable tools' `document_id` / `app_token` parameter also accepts a Wiki node token or a full Feishu URL — the plugin resolves it transparently.
 
 ### Official API -- Documents (7 tools)
 
@@ -494,10 +509,12 @@ Skills are automatically available when the plugin is installed.
 |------------|-------|----------|---------|
 | Cookie | `sl_session` | 12h max-age | Auto-refreshed every 4h via heartbeat |
 | App Token | `tenant_access_token` | 2h | Auto-managed by SDK |
-| User OAuth | `user_access_token` | ~2h | Auto-refreshed via `refresh_token`, saved to `.env` |
+| User OAuth | `user_access_token` | ~2h | Auto-refreshed via `refresh_token`, saved to MCP config |
 
 When the cookie expires (after ~12-24h without heartbeat), re-login at feishu.cn and update `LARK_COOKIE`. Use `get_login_status` to check health proactively.
 
+If UAT refresh fails with `invalid_grant`, re-run `npx feishu-user-plugin oauth` and restart Claude Code / Codex. v1.3.5+ also re-reads the persisted MCP config before refreshing, so duplicate MCP processes can adopt a token already rotated by another process instead of retrying a stale refresh token.
+
 ## Project Structure
 
 ```
@@ -509,7 +526,7 @@ feishu-user-plugin/
 │       ├── SKILL.md         # Main skill definition (trigger, tools, auth)
 │       └── references/      # 8 skill reference docs + CLAUDE.md
 ├── src/
-│   ├── index.js             # MCP server entry point (67 tools)
+│   ├── index.js             # MCP server entry point (75 tools)
 │   ├── client.js            # User identity client (Protobuf gateway)
 │   ├── official.js          # Official API client (REST, UAT)
 │   ├── utils.js             # ID generators, cookie parser

package/package.json

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

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

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

package/scripts/test-uat-race.js

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

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

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

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

@@ -6,7 +6,7 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - **Official API** (app credentials): Read group messages, docs, tables, wiki, drive, contacts, upload files
 - **User OAuth UAT** (user_access_token): Read P2P chat history, list all user's chats
 
-## Tool Categories (67 tools)
+## Tool Categories (75 tools)
 
 ### User Identity — Messaging (reverse-engineered, cookie-based)
 - `send_to_user` — Search user + send text (one step, most common). Returns candidates if multiple matches.
@@ -32,7 +32,7 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - **All docx + bitable + drive create/read/write tools are UAT-first**: when UAT is configured, every operation (create/edit/delete doc blocks, bitable tables/fields/views/records, drive folders) tries the user's token first and falls back to app token on failure. This keeps resources consistently owned by the user and avoids 403 errors when the app can't access user-created resources. Read-only tools (e.g. `read_doc`, `get_doc_blocks`, `list_bitable_tables`) are also UAT-first so user-owned resources remain readable.
 
 ### Official API Tools (app credentials)
-- `list_chats` / `read_messages` — Chat history (read_messages accepts chat name, oc_ ID, or numeric ID; auto-resolves via bot's group list → im.chat.search → search_contacts). **Auto-falls back to UAT for external groups the bot cannot access.** Returns newest messages first by default. Messages include sender names.
+- `list_chats` / `read_messages` — Chat history (read_messages accepts chat name, oc_ ID, or numeric ID; auto-resolves via bot's group list → im.chat.search → search_contacts). **Auto-falls back to UAT for external groups the bot cannot access.** Returns newest messages first by default. Messages include sender names. **v1.3.5**: `merge_forward` messages now auto-expand into their child messages (2 images + 4 texts, with original sender / time / origin chat preserved); text messages get `urls[]` + `feishuDocs[]` extracted so agents can feed them straight into `read_doc` / WebFetch. Disable expansion with `expand_merge_forward=false`.
 - `send_message_as_bot` — Bot sends message to any chat (text, post, interactive, etc.)
 - `reply_message` / `forward_message` — Message operations (as bot)
 - `delete_message` / `update_message` — Recall or edit bot's own messages
@@ -48,15 +48,49 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - `list_bitable_views` / `create_bitable_view` / `delete_bitable_view` — View management (grid, kanban, gallery, form, gantt, calendar)
 - `search_bitable_records` / `get_bitable_record` — Query records
 - `batch_create_bitable_records` / `batch_update_bitable_records` / `batch_delete_bitable_records` — Record CRUD (single or batch, max 500/call)
-- `list_wiki_spaces` / `search_wiki` / `list_wiki_nodes` — Wiki
+- `list_wiki_spaces` / `search_wiki` / `list_wiki_nodes` / `get_wiki_node` — Wiki (v1.3.4 adds `get_wiki_node` which resolves a wiki node token to its underlying `obj_type` + `obj_token`, so you can feed the node straight into `read_doc`, bitable tools, etc.)
 - `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).
+- `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
 
 ## Usage Patterns
 
+### Wiki-hosted content (docx / bitable / sheet)
+All docx and bitable tools now accept three input forms for their `document_id` / `app_token` parameter:
+- Native token (unchanged): `doccnXXX`, `docxXXX`, `bascnXXX`, ...
+- Wiki node token: `wikcnXXX`, `wikmXXX`, `wiknXXX`
+- Full Feishu URL: `https://xxx.feishu.cn/docx/XXX`, `.../wiki/XXX`, `.../base/XXX`
+The plugin resolves wiki nodes to their underlying `obj_token` via `getWikiNode`, then calls the normal docx / bitable endpoint. Results are cached for 10 min to avoid repeated node lookups.
+
+Create content directly into a Wiki space:
+- `create_doc` / `create_bitable` accept optional `wiki_space_id` (+ `wiki_parent_node_token`). The plugin creates the resource in drive, then calls `wiki/v2/spaces/{space_id}/nodes/move_docs_to_wiki` to attach it — returns `wikiNodeToken` on immediate success, or `wikiAttachTaskId` if Feishu queues the move.
+
+### Document images
+Read — `download_image` with `doc_token` + `image_token` returns the image as MCP image content (base64 + mimeType). `doc_token` accepts native id / wiki node / URL.
+Write — `create_doc_block` now has image shortcuts:
+- `image_path` (absolute local file path) → plugin creates an image block, uploads the pixels via `drive/v1/medias/upload_all`, and patches the block with the uploaded token.
+- `image_token` (already uploaded) → plugin creates block and attaches token.
+`update_doc_block` accepts `image_token` to swap the picture in an existing image block.
+
+### OKR
+1. `list_okr_periods` — find the period id for current quarter.
+2. `list_user_okrs(user_id=<open_id>, period_ids=[...])` — list the target user's OKRs.
+3. `get_okrs(okr_ids)` — batch fetch full objective + key result structure with progress + alignments.
+`user_id` is required — use your own open_id (from `get_login_status` / `search_contacts`) to read your own OKRs, or a colleague's open_id for theirs (subject to permissions).
+
+### Calendar
+1. `list_calendars` — get your calendars; the one with `type=primary` is your personal calendar.
+2. `list_calendar_events(calendar_id, start_time=<unix_sec>, end_time=<unix_sec>)` — list events in a time window.
+3. `get_calendar_event(calendar_id, event_id)` — full details (attendees, location, attachments, meeting link).
+
+### External-group message read (hardened in v1.3.4)
+`read_messages` and `read_p2p_messages` now expose a `via` field in the response (`"bot"`, `"user"`, or `"contacts"`) so callers can tell which identity actually read the data. When bot fails with a known code (external tenant / no permission / not in chat) the plugin hops straight to UAT; transient errors (rate limit / 5xx / ECONNRESET / fetch timeout) retry once with a 2 s delay before falling back. When UAT isn't configured, the error message now tells the user to run `npx feishu-user-plugin oauth` instead of leaking the raw Feishu payload.
+
 ### Messaging
 - Send text as yourself → `send_to_user` or `send_to_group`
 - Send image → `upload_image` → `send_image_as_user`
@@ -274,7 +308,22 @@ Two known root causes, both fixed in v1.3.3:
 ### If UAT refresh fails with "invalid_grant"
 - The refresh token has expired or been revoked — auto-refresh cannot recover this
 - **Fix**: Re-run OAuth: `npx feishu-user-plugin oauth`
-- Then restart Claude Code
+- Then restart Claude Code / Codex so running MCP server processes load the new token
+- **v1.3.5+ hardening** (no manual action required, fixes the common case):
+  - Cross-process file lock at `~/.claude/feishu-uat-refresh.lock` (`O_CREAT|O_EXCL`, 30 s stale detection) — at most one MCP process refreshes at a time.
+  - Inside the critical section the lock holder re-reads `~/.claude.json` to see if a peer already rotated the token; if so, it adopts the fresh token instead of consuming an already-invalidated refresh token.
+  - This closes the "Codex spawned 6 MCP servers, all shared the same refresh_token, all raced to refresh" failure mode observed on 2026-04-23.
+  - `get_login_status` now does a real UAT health check (calls `listChatsAsUser({pageSize:1})`) — no more "token configured but actually 401" surprises.
+
+### If multiple MCP server processes keep spawning
+- Observed on Codex + Claude Code when the client respawns the server for each tool session without cleaning up the previous one. 6 concurrent `src/index.js` processes is not unusual under heavy use.
+- v1.3.5 neutralises the damage (UAT refresh serialised via file lock) but the stale processes still consume memory.
+- **Manual cleanup when you notice**: `pkill -f 'feishu-user-plugin/src/index.js'` — the client will respawn one fresh process on the next tool call.
+
+### If a create_* tool warns "UAT failed, created as BOT"
+- v1.3.5 added an explicit `⚠️` warning to MCP responses whenever `_asUserOrApp` silently fell back to bot identity for a write (create_doc / create_bitable / create_folder / create_doc_block / ...). Before v1.3.5 this was silent and led to the "teammate can read my 'private' doc" issue.
+- **Cause**: your UAT is failing (expired / scope missing / race) so the plugin reached for bot credentials. The resulting resource is owned by the shared bot, tenant-readable by default, NOT by you.
+- **Fix**: run `npx feishu-user-plugin oauth` and restart Claude Code / Codex. If the resource needs to be yours, delete the bot-owned copy and recreate after UAT is valid.
 
 ### If OAuth fails with "Missing LARK_APP_ID"
 - `oauth.js` reads credentials from `~/.claude.json` MCP config (not .env)
@@ -359,6 +408,7 @@ When making ANY code change (new tools, bug fixes, features), update ALL of thes
 
 **本仓库内：**
 - `CLAUDE.md` — tool count, tool list, usage patterns, known limitations
+- `AGENTS.md` — **每次改 CLAUDE.md 必须同步**：正文（第 2 行起）与 CLAUDE.md 完全一致，仅首行标题保留 `# feishu-user-plugin — Codex Instructions`。同步命令：`tail -n +2 CLAUDE.md > /tmp/body.md && { echo "# feishu-user-plugin — Codex Instructions"; cat /tmp/body.md; } > AGENTS.md`
 - `README.md` — tool count (badge + heading + tool table), feature highlights, OpenClaw/Claude Code config examples
 - `ROADMAP.md` — check off completed items, add new findings
 - `package.json` — version, description (tool count)
@@ -421,6 +471,55 @@ Steps:
 3. `git add <files> && git commit -m "v1.x.x: description"`
 4. `git tag v1.x.x && git push && git push --tags`
 5. GitHub Actions verifies tag matches package.json, then auto-publishes to npm
+6. **After npm confirms the new version is live, draft a release announcement in Chinese for the "AI技术解决（内部）" Feishu group and show it to the user for approval BEFORE sending.** Do not send until the user explicitly approves.
+
+### Release announcement rules (every release)
+After a successful publish, draft a group announcement to "AI技术解决（内部）" (chat_id `7599552782038813643`) and ALWAYS show it to the user for review first. Only send after explicit approval.
+
+**Transport**: `send_post_as_user` (rich-text post). No @-mentions — announcements are impersonal broadcasts. No emojis. No marketing language.
+
+**Structure** (in this order; omit a section if it doesn't apply this release):
+
+```
+feishu-user-plugin vX.Y.Z 发布
+
+<一到两句开篇总结本次发布的主题，陈述语气，不推销>
+
+修复
+• <缺陷描述>：<根因与修复机制，引用具体错误码/接口名/参数>
+• ...
+
+新增
+• 新增 <tool 名> 工具：<一句话功能描述>。<关键约束或调用条件>
+• ...
+
+调整
+• <行为变化的描述>
+• ...
+
+下版本计划
+• <条目>
+• ...
+
+升级方式
+• 重启 Claude Code / Codex 即可自动拉取 X.Y.Z
+• <若有相关新日志/错误提示，说明怎么应对>
+• 建议复测 N 个场景：<场景 1>、<场景 2>、<场景 3>
+```
+
+**写作规范**:
+- **开篇**：一到两句陈述式总结，不宣传、不夸大。参考 v1.3.2："本次更新主要补齐了 X 能力，并修复了 Y 问题；同时将 Z 统一调整为 ..."
+- **每条 bullet**：先写用户可见现象，再写底层机制。引用具体错误码（如 1770032 / 91403）、接口名（如 create_doc_block）、参数名（如 RichText.atIds）——专业读者信赖的是细节
+- **字符**：bullet 用 `•`（U+2022），不用 `-` 或 `*`；代码/工具名在正文中直接写，不加反引号
+- **禁用**：emoji、🔴🟡🟢 之类严重度标记、`@` 任何人、营销词（"强大"、"全新"、"重磅"）、夸张修辞
+- **语气**：技术 release note 的中性语气，像写给同行的内部更新。参考 v1.3.2 全文
+- **长度**：单屏为宜，一般 400–700 汉字。每条 bullet 一到三行
+- **下版本计划**：复制自上一版公告仍未完成的条目 + 本次发布中暴露的新方向。本版已完成的条目必须删除
+- **升级方式**：至少包含重启指令；若本次修了某类错误（如 APP_ID 校验），列出对应诊断日志字样；以"建议复测 N 个场景"收尾，场景要具体可操作
+
+**结尾**：不加 CHANGELOG 链接（v1.3.2 风格未含链接，群内读者不需要）。
+
+**发送前**：始终先用 `send_to_user` 或类似工具发给用户自己审核，或直接以文本形式贴在对话里等用户批准。用户说"发"才调 `send_post_as_user` 到目标群。
 
 ### Syncing to team-skills (after any CLAUDE.md or skills change)
 1. Copy CLAUDE.md to skill reference: `cp CLAUDE.md skills/feishu-user-plugin/references/CLAUDE.md`
@@ -434,6 +533,19 @@ Steps:
 - For Cookie tools: need active session, test via MCP tool call
 - Always verify `_safeSDKCall` handles the response format (multipart uploads return data at top level, not nested under `.data`)
 
+## OAuth Scopes (when re-running `npx feishu-user-plugin oauth`)
+
+The v1.3.4 tools require additional scopes on the app + UAT:
+
+| Feature | Scopes to enable on app + include in OAuth |
+|---------|-------------------------------------------|
+| 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) |
+| 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.
+
 ## Known Limitations
 - CARD message type (type=14) not yet implemented — complex JSON schema
 - External tenant users may not be resolvable via `get_user_info` (contact API scope limitation)

package/src/doc-blocks.js

@@ -0,0 +1,70 @@
+// 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.
+
+// docx v1 block_type enum (relevant subset).
+// Docs: https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document-block/create
+const BLOCK_TYPE = {
+  PAGE:        1,
+  TEXT:        2,
+  HEADING1:    3,
+  HEADING2:    4,
+  HEADING3:    5,
+  HEADING4:    6,
+  HEADING5:    7,
+  HEADING6:    8,
+  HEADING7:    9,
+  HEADING8:   10,
+  HEADING9:   11,
+  BULLET:     12,
+  ORDERED:    13,
+  CODE:       14,
+  QUOTE:      15,
+  EQUATION:   16,
+  TODO:       17,
+  BITABLE:    18,
+  CALLOUT:    19,
+  CHAT_CARD:  20,
+  DIAGRAM:    21,
+  DIVIDER:    22,
+  FILE:       23,
+  GRID:       24,
+  GRID_COL:   25,
+  IFRAME:     26,
+  IMAGE:      27,
+  TABLE:      31,
+};
+
+/**
+ * The image-block creation flow on Feishu docx v1 is three steps:
+ *   1. POST .../blocks/<parent>/children with an empty image placeholder:
+ *        { block_type: 27, image: {} }
+ *      This returns a real block_id for the image slot.
+ *   2. POST /open-apis/drive/v1/medias/upload_all with parent_type=docx_image
+ *      and parent_node=<that block_id> to upload the pixels. Returns file_token.
+ *   3. PATCH .../blocks/<block_id> with { replace_image: { token: file_token } }
+ *      to populate the placeholder with the uploaded image.
+ *
+ * See official.js::createDocBlockWithImage which orchestrates all three steps.
+ */
+
+/** Empty image block used as the placeholder in step 1. */
+function buildEmptyImageBlock() {
+  return { block_type: BLOCK_TYPE.IMAGE, image: {} };
+}
+
+/** Patch body for step 3 — attaches an uploaded image_token to a placeholder block. */
+function buildReplaceImagePayload(imageToken) {
+  if (!imageToken) throw new Error('buildReplaceImagePayload: imageToken is required');
+  return { replace_image: { token: imageToken } };
+}
+
+module.exports = {
+  BLOCK_TYPE,
+  buildEmptyImageBlock,
+  buildReplaceImagePayload,
+};

package/src/error-codes.js

@@ -0,0 +1,78 @@
+// Feishu error-code classification for read_messages fallback routing.
+//
+// The v1.3.2 read_messages handler catches any bot failure and unconditionally
+// retries with UAT. That's cheap when the bot fails fast, but it has two flaws
+// in v1.3.3:
+//   • Transient errors (rate-limit, network stalls) are treated the same as
+//     permanent permission errors — the UAT path runs when a 2-second retry
+//     would have worked.
+//   • When UAT is absent, the raw Feishu payload leaks to the user verbatim,
+//     with no hint that OAuth is the fix.
+//
+// This table classifies known codes into three buckets:
+//   'uat'     — permanent bot failure; hop straight to UAT.
+//   'retry'   — likely transient; caller should retry once (after short delay)
+//               and fall through to UAT if still failing.
+//   'unknown' — not seen before; preserve v1.3.3 behaviour (try UAT silently).
+
+const FAILURE_MAP = {
+  // External tenant — bot lives in a different tenant, will never be granted.
+  240001: { action: 'uat', reason: 'bot_external_tenant' },
+  // No permission for the resource (scope missing, or chat restricts bot reads).
+  70009:  { action: 'uat', reason: 'bot_no_permission' },
+  // Bot is not a member of the chat.
+  70003:  { action: 'uat', reason: 'bot_not_in_chat' },
+  99991668: { action: 'uat', reason: 'bot_not_in_chat' },
+  // Chat does not exist (from the bot's POV — may still be accessible to user).
+  19001:  { action: 'uat', reason: 'bot_chat_not_found' },
+
+  // Rate limited — Feishu throttles, try once more after a brief pause.
+  42101:  { action: 'retry', reason: 'bot_rate_limited' },
+  // Frequency control variants occasionally observed.
+  99991400: { action: 'retry', reason: 'bot_rate_limited' },
+};
+
+// HTTP-status / network-error patterns that warrant one retry.
+// Axios-wrapped messages from @larksuiteoapi/node-sdk embed the http status
+// into _safeSDKCall's rethrown message. We match those substrings.
+const TRANSIENT_PATTERNS = [
+  /HTTP 5\d\d/i,         // Any 5xx from upstream
+  /ECONNRESET/i,
+  /ETIMEDOUT/i,
+  /fetch timeout after/i, // from utils.fetchWithTimeout
+  /socket hang up/i,
+];
+
+/**
+ * Classify an error thrown by a bot-API path.
+ * Input is either the Feishu code number (preferred) or the Error object —
+ * the code is extracted from the message if present.
+ *
+ * Output: { action: 'uat' | 'retry' | 'unknown', reason: string, code: number|null }
+ */
+function classifyError(errOrCode) {
+  let code = null;
+  let msg = '';
+  if (typeof errOrCode === 'number') {
+    code = errOrCode;
+  } else if (errOrCode && typeof errOrCode === 'object') {
+    msg = errOrCode.message || String(errOrCode);
+    // _safeSDKCall formats as "label failed (HTTP N, code=XXX): ..." or "label failed (CODE): ..."
+    const m = msg.match(/code[=(]\s*(\d+)/i) || msg.match(/failed\s*\((\d+)\)/i);
+    if (m) code = parseInt(m[1], 10);
+  }
+
+  if (code != null && FAILURE_MAP[code]) {
+    return { ...FAILURE_MAP[code], code };
+  }
+  for (const re of TRANSIENT_PATTERNS) {
+    if (re.test(msg)) return { action: 'retry', reason: 'bot_network_error', code };
+  }
+  return { action: 'unknown', reason: 'bot_unknown_error', code };
+}
+
+module.exports = {
+  classifyError,
+  FAILURE_MAP,
+  TRANSIENT_PATTERNS,
+};