feishu-user-plugin 1.3.14 → 1.3.16

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.14",
+  "version": "1.3.16",
   "description": "All-in-one Feishu MCP server + CLI tool for Claude Code — send messages as yourself, read chats (auto-expanded merge_forward), manage docs / bitable / wiki (full CRUD) / drive / OKR (with progress writes) / calendar (read+write) / Tasks v2 / multi-profile auto-switch / real-time WS events. 85 tools + 9 prompts, 3 auth layers.",
   "author": {
     "name": "EthanQC"

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "feishu-user-plugin",
   "displayName": "Feishu MCP for Claude Code & Codex",
   "description": "All-in-one Feishu MCP server + CLI tool for Claude Code / Codex / Cursor / scripts — 85 tools across 3 auth layers (cookie / app / OAuth). Send as you, read groups, manage docs / bitable / wiki / drive / calendar / tasks / OKR.",
-  "version": "1.3.14",
+  "version": "1.3.16",
   "author": {
     "name": "EthanQC"
   },

package/.mcpb/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "feishu-user-plugin",
   "display_name": "Feishu MCP for Claude Code & Codex",
-  "version": "1.3.14",
+  "version": "1.3.16",
   "description": "All-in-one Feishu MCP server + CLI tool for Claude Code / Codex / Cursor / scripts — 85 tools across 3 auth layers (cookie / app / OAuth). Send as you, read groups, manage docs / bitable / wiki / drive / calendar / tasks / OKR.",
   "long_description": "feishu-user-plugin is a local stdio MCP server (and shell CLI tool) that bridges Feishu / Lark and any MCP client (Claude Code, Codex, Cursor, Windsurf, OpenClaw, Claude Desktop). It exposes 85 tools across three auth layers: cookie + protobuf for sending messages as the real user (a capability not available through the official bot API), Feishu Open Platform app credentials for groups / docs / bitable / wiki / drive / calendar / tasks / OKR, and user OAuth (UAT) for P2P chat reading and user-owned resource creation.",
   "author": {

package/CHANGELOG.md

@@ -4,6 +4,44 @@ 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.16] - 2026-06-06
+
+修掉发现类读路径的身份盲区：上传到个人空间的文件此前找不到、也因此删不掉。`list_files` / `search_docs` / `search_wiki` / `get_wiki_node` 四条读路径改为 UAT 优先（bot fallback 保留）。85 工具数不变，list_files / search_docs / search_wiki 三个 schema 新增分页参数，无 breaking API。
+
+### Added
+
+- **list_files 看得见你的个人空间了（用户报障修复）**：此前 `list_files` 走纯 app token，bot 对个人空间（"我的空间"）文件夹 403，导致 `upload_drive_file` 走 UAT 传上去的文件**不可发现、也不可删除**（`manage_drive_file(action=delete)` 需要的 file_token 拿不到）。现在 UAT 优先、bot fallback：配置 UAT 后空 `folder_token` 列你自己的"我的空间"根目录。新增 `page_size` / `page_token` 入参与 `nextPageToken` 返回；root 空结果且走 bot 路径时附 `scopeHint` 解释 bot root ≠ 我的空间。（`src/clients/official/drive.js`）
+- **search_docs / search_wiki 分页游标**：新增 `page_size` / `offset` 入参，`hasMore` 时返回 `nextOffset` 直接回填即可翻页；此前只有 `hasMore` 没有可用游标，截断的尾部恰好可能藏着要找的个人空间文档。异常的 `has_more:true` 空页不发 cursor，防止翻页死循环。坏参数（NaN / 负数）收敛为非负整数后才发给飞书。
+
+### Changed
+
+- **search_docs / search_wiki / get_wiki_node 改 UAT-first**：suite 搜索 API 只索引调用身份可见的内容，app 身份搜不到个人空间文档（报障里上传的 PDF 就是这样消失的）。三条路径与 `list_files` 一并走 `_asUserOrApp`（UAT 优先、bot fallback，被迫走 bot 时返回 ⚠ fallbackWarning），响应统一带 `viaUser` 标明视角归属。`get_wiki_node` 保持裸 node 返回形状（resolver 兼容），additive 附加 `viaUser` / `fallbackWarning`；obj_token 合成正则不受新错误形状影响（953001 与 live 实测 131005 双分支测试钉死）。
+- **依赖升级**：protobufjs 7.5.6 → 8.6.0（cookie protobuf 发送层经真实发送探针 + 读回验证）；`@larksuiteoapi/node-sdk` 1.63.1 → 1.66.0（official API 读路径实测）。
+- **MCP Registry namespace** 指向 `io.github.zhuzhen-team`（仓库迁移收尾）。
+
+### Test scenarios
+
+- 配置 UAT 后调 `list_files`（空参）应列出你"我的空间"根目录且 `viaUser:true`
+- `upload_drive_file` 上传 → `list_files` 拿 file_token → `manage_drive_file(action=delete)` 删除 → 再 `list_files` 确认消失
+- `search_docs` 搜个人空间上传的 PDF 标题应能命中，`page_size`+`offset` 翻页两页无重叠
+
+## [1.3.15] - 2026-05-31
+
+两条增强：文档建表格不再让 agent 猜 block_type；UAT 频繁重新授权的根因（良性 refresh_token 轮换竞态被误判为撤销）修掉。无 schema 变化、无新工具（仍 85）、无 breaking API。升级后重启 Claude Code / Codex 自动拉 v1.3.15。
+
+### Added
+
+- **manage_doc_block 新增 table 创建模式（mode F）**：`manage_doc_block(action=create, table={rows, columns, cells?, column_width?, header_row?, header_column?})` 一步建表 + 填格。此前 agent 要自己拼 table block 并猜 `block_type`（猜成 40 → 飞书报 `invalid_param`）；现在插件内部建 `block_type=31` 表、由飞书自动生成 `block_type=32` 单元格、逐格 UPDATE 单元格自带的空文本块（无遗留空块）。单元格 ID 行优先解析自创建响应，回退到 scoped `getBlockChildren`（不吃整文档 500 块上限），解析不全则报错而非静默丢内容。返回 `tableBlockId` + 行优先 `cells` 网格。`skills/feishu-user-plugin/references/doc.md` 同步补建表 + 决策树指引。
+
+### Fixed
+
+- **UAT refresh `invalid_grant` 良性轮换竞态自愈**：频繁收到飞书"授权操作通知"、"没撑过一晚上"的根因。飞书 refresh_token 每次刷新滚动轮换；当跨进程互斥失效时（20s 锁超时兜底，或 v1.3.14 升级期间新旧锁路径 `~/.claude/feishu-uat-refresh.lock` vs `~/.feishu-user-plugin/uat-refresh.lock` 不对齐），并发刷新的输家拿 `invalid_grant`，此前 `refreshUAT` 直接判 `UAT_REVOKED` 并提示重跑 oauth——而赢家此刻早已把有效新 token 落盘。现在 `invalid_grant` 时先快照已发送的 refresh_token、回查磁盘，若已有"不同且仍有效"的 token（peer 赢了轮换）就采用并恢复，只有磁盘也是同一个死 token 才真判撤销；按 client 状态判定（而非 `adoptPersistedUATIfNewer` 返回值）兼顾 in-process / credentials-monitor hot-reload race。（`src/auth/uat.js`）
+
+### Test scenarios
+
+- 多进程 / 多版本并发刷 UAT 时，良性轮换不再弹"授权操作通知"、不再提示重跑 oauth（`auth_time` 不跳）
+- `manage_doc_block(action=create, table={rows:2,columns:2,cells:[["A","B"],["C","D"]]})` 在文档里生成 2×2 表、四格有内容、无空行
+
 ## [1.3.14] - 2026-05-21
 
 **TL;DR**：纯收紧的 bug fix / security release。无 schema 变化、无新工具、无 breaking API。升级后重启 Claude Code / Codex 自动拉 v1.3.14；如果之前还没跑过 `migrate --confirm`，**强烈建议**跑一次（canonical store 是 v1.3.7+ 推荐路径，v1.3.14 把 UAT refresh 锁也搬过来完成最后一块）。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "mcpName": "io.github.EthanQC/feishu-user-plugin",
-  "version": "1.3.14",
+  "mcpName": "io.github.zhuzhen-team/feishu-user-plugin",
+  "version": "1.3.16",
   "description": "All-in-one Feishu MCP server + CLI tool for Claude Code / Codex / Cursor / scripts — 85 tools across 3 auth layers (cookie / app / OAuth). Send as you, read groups, manage docs / bitable / wiki / drive / calendar / tasks / OKR.",
   "main": "src/index.js",
   "bin": {
@@ -64,7 +64,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^16.4.7",
     "feishu-docx": "^0.7.0",
-    "protobufjs": "^7.5.6"
+    "protobufjs": "^8.6.0"
   },
   "devDependencies": {
     "husky": "^9.1.7"

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

@@ -1,7 +1,7 @@
 ---
 name: feishu-user-plugin
-version: "1.3.14"
-description: "All-in-one Feishu MCP server + CLI tool — send messages as yourself (incl. batch_send), read group/P2P chats (auto-expands merge_forward), manage docs/tables/wiki (full CRUD)/drive, OKR (with progress writes), calendar (read+write), Tasks v2, multi-profile auto-switch, real-time WS events. v1.3.14: UAT refresh-lock moved to canonical home (Codex-only users now get cross-process mutex), invalid_grant flips identity to UAT_REVOKED with clear oauth re-run guidance, refresh-error redaction (no raw response body in Error.message), three-stage adoptPersistedUATIfNewer race-shield, cookie heartbeat ws-owner-gated (no more N-times API spam from 30+ concurrent sessions), OAuth/setup all fetch calls timeout-bounded, oauth-auto.js dead code with token leak removed, OAuth browser callback no longer displays token bytes, decodeTokenExpiry malformed-JWT warning deduped, Lark Desktop reactor cold-start debounce fixed, 27 new fixture-based tests (test-uat-lifecycle + test-cookie-heartbeat) plus the cross-process race test repaired, TROUBLESHOOTING.md grew 4 sections (frequent consent notification / UAT-not-refreshing / mixed-version upgrade window / migrate-then-stale-env)."
+version: "1.3.16"
+description: "All-in-one Feishu MCP server + CLI tool — send messages as yourself (incl. batch_send), read group/P2P chats (auto-expands merge_forward), manage docs/tables/wiki (full CRUD)/drive, OKR (with progress writes), calendar (read+write), Tasks v2, multi-profile auto-switch, real-time WS events. v1.3.16: discovery reads go UAT-first — list_files / search_docs / search_wiki / get_wiki_node previously ran app-token-only, so the bot 403'd on personal-space (我的空间) folders and user-uploaded files were undiscoverable and thus undeletable (manage_drive_file needs a file_token only list_files can provide); now they try your user identity first with bot fallback (+⚠ fallbackWarning) and every response carries viaUser. list_files gains page_size/page_token (+nextPageToken), both search tools gain page_size/offset (+nextOffset cursor; withheld on an abnormal empty page to prevent paging loops). Deps: protobufjs 8.6, lark-sdk 1.66."
 allowed-tools: send_to_user, send_to_group, send_as_user, send_image_as_user, send_file_as_user, send_post_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, manage_profile_hints, read_p2p_messages, list_user_chats, list_chats, read_messages, search_messages, send_message_as_bot, reply_message, forward_message, delete_message, update_message, add_reaction, delete_reaction, pin_message, create_group, update_group, list_members, manage_members, search_docs, read_doc, get_doc_blocks, create_doc, manage_doc_block, read_doc_markdown, manage_bitable_app, manage_bitable_table, manage_bitable_field, manage_bitable_view, manage_bitable_record, upload_bitable_attachment, list_wiki_spaces, search_wiki, list_wiki_nodes, get_wiki_node, create_wiki_node, update_wiki_node, move_wiki_node, copy_wiki_node, delete_wiki_node, list_files, create_folder, upload_drive_file, manage_drive_file, upload_image, upload_file, download_message_resource, download_doc_image, list_user_okrs, get_okrs, list_okr_periods, create_okr_progress_record, list_okr_progress_records, delete_okr_progress_record, list_calendars, list_calendar_events, get_calendar_event, create_calendar_event, update_calendar_event, delete_calendar_event, respond_calendar_event, get_freebusy, list_tasks, get_task, create_task, update_task, complete_task, delete_task, manage_task_members, get_new_events, manage_ws_status
 user_invocable: true
 ---

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

@@ -17,11 +17,23 @@
 1. 用 `create_doc` 创建新文档（传入标题和可选 folder_id）
 2. 返回文档 ID
 
+### 在文档里建表格
+1. 用 `manage_doc_block(action=create, document_id, parent_block_id, table={...})` 建表
+   - `parent_block_id` 用 `document_id` 表示文档根（或某个块 ID 表示插在该块下）
+   - `table` 形如 `{"rows":2,"columns":2,"cells":[["姓名","角色"],["Ann","PM"]]}`：`cells` 行优先，可省略或留空字符串表示空格
+   - 插件内部建 `block_type=31` 表格、由飞书自动生成单元格（`block_type=32`）、逐格填内容——**不要自己用 `children` 拼 table block 或猜 block_type**（表格是 31 不是 40，猜错会报 `invalid_param`）
+2. 返回 `tableBlockId` + 行优先的 `cells` 单元格 ID 网格
+
+### 写决策树等纯文本结构
+表格只用于真正的二维数据；决策树、流程、缩进结构用 `children` 里的文本块（`block_type=2`）+ 代码块（`block_type=14`）表达即可，不依赖表格线。
+
 ## 示例
 - `/doc search MCP 协议`
 - `/doc read doxcnXXXXXX`
 - `/doc create 本周工作总结`
+- `/doc 在 doxcnXXXX 里建一个 2×2 表格，表头 姓名/角色`
 
 ## 注意
 - 文档操作使用 Official API（需要 LARK_APP_ID）
 - 搜索结果受机器人权限范围限制
+- 建表格走 `manage_doc_block` 的 `table` 模式，不要手拼 block——表格 `block_type=31`、单元格 `32`

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

@@ -7,18 +7,24 @@
 
 ### 列出文件
 1. 用 `list_files` 列出文件夹内容
-   - 不传 folder_token 则列出根目录
+   - 不传 folder_token 则列出根目录（配置了 UAT 时是**你的**"我的空间"根目录）
    - 传入 folder_token 则列出指定文件夹
+   - 结果多时用 `page_token`（来自上一页的 `nextPageToken`）翻页
 
 ### 创建文件夹
 1. 用 `create_folder` 创建新文件夹
    - 传入 name 和可选的 parent_token
 
+### 删除 / 移动 / 复制文件
+1. 用 `list_files` 找到目标的 token
+2. 用 `manage_drive_file` 操作（action=delete/move/copy，必传 type）
+
 ## 示例
 - `/drive list` — 列出根目录文件
 - `/drive list folderXxx` — 列出指定文件夹
 - `/drive create 项目资料` — 在根目录创建文件夹
+- `/drive 删掉根目录里的 xxx.pdf` — list_files 找 token 后 manage_drive_file 删除
 
 ## 注意
 - 使用 Official API，需要 LARK_APP_ID
-- 文件列表受机器人权限范围限制
+- `list_files` UAT-first（v1.3.16+）：配置了 UAT 就以你的身份列文件（个人空间可见）；否则以 bot 身份，只能看到共享给 bot 的文件夹。返回的 `viaUser` 标明视角归属

package/src/auth/uat.js

@@ -163,6 +163,12 @@ async function refreshUAT(client) {
       return client._uat;
     }
     if (!client._uatRefresh) throw new Error('UAT expired and no refresh token. Run: npx feishu-user-plugin oauth');
+    // Snapshot the refresh_token we are about to send BEFORE awaiting. A peer
+    // in-process refresh or the credentials monitor can hot-reload
+    // client._uatRefresh during the round-trip; the invalid_grant self-heal
+    // below must compare against the token actually sent, not a field that may
+    // have already rotated. (Codex review, PR #111.)
+    const attemptedRefresh = client._uatRefresh;
     const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
@@ -170,7 +176,7 @@ async function refreshUAT(client) {
         grant_type: 'refresh_token',
         client_id: client.appId,
         client_secret: client.appSecret,
-        refresh_token: client._uatRefresh,
+        refresh_token: attemptedRefresh,
       }),
     });
     const data = await res.json();
@@ -187,6 +193,37 @@ async function refreshUAT(client) {
       // UAT_REVOKED, and withIdentityFallback can give the LLM clear guidance.
       const isInvalidGrant = errCode === 'invalid_grant' || errCode === 20064;
       if (isInvalidGrant) {
+        // v1.3.15 — self-heal a benign refresh_token rotation race before
+        // declaring the 7-day chain dead. When cross-process mutual exclusion
+        // is defeated (lock-acquire timeout fallthrough above, or a transient
+        // mixed-version upgrade window where old/new instances use different
+        // lock paths), two processes can refresh with the same refresh_token;
+        // Feishu rotates it for the winner and rejects the loser with
+        // invalid_grant. By the time the loser lands here, the winner has very
+        // likely already persisted a fresh, valid, DIFFERENT token to disk.
+        // Re-read disk: if it now holds a different, still-valid token, our
+        // invalid_grant just means "our copy was rotated away" — adopt it and
+        // recover, instead of flipping to UAT_REVOKED and pushing the user
+        // through a needless `oauth` re-consent (the "授权操作通知 没撑过一晚上"
+        // symptom). Only when disk still holds the SAME (now-dead) refresh_token
+        // is this a genuine revocation. Covered by test-uat-lifecycle
+        // "invalid_grant + peer rotated fresh token to disk".
+        now = Math.floor(Date.now() / 1000);
+        // Best-effort re-sync from disk (a no-op if a peer/monitor already
+        // updated this client in memory). Then recover iff we now hold a
+        // DIFFERENT, still-valid token than the one we actually sent — this
+        // covers both the cross-process race (disk holds the winner) and the
+        // in-process / hot-reload race (client already holds the winner).
+        // Gating on the resulting client state, rather than on
+        // adoptPersistedUATIfNewer()'s return value, is what lets the
+        // hot-reload case recover (adopt is a no-op there). (Codex review, PR #111.)
+        adoptPersistedUATIfNewer(client);
+        if (client._uat
+            && client._uatRefresh !== attemptedRefresh
+            && client._uatExpires > now + 300) {
+          console.error('[feishu-user-plugin] UAT invalid_grant on the sent refresh_token; a different valid token is present (peer won the rotation) — adopted, no re-consent needed');
+          return client._uat;
+        }
         try {
           const { _refineIdentity, IdentityState } = require('./identity-state');
           _refineIdentity(client, IdentityState.UAT_REVOKED);

package/src/clients/official/docs.js

@@ -11,14 +11,31 @@ module.exports = {
   // --- Docs ---
 
   async searchDocs(query, { pageSize = 10, pageToken } = {}) {
-    const res = await this._safeSDKCall(
-      () => this.client.request({
-        method: 'POST', url: '/open-apis/suite/docs-api/search/object',
-        data: { search_key: query, count: pageSize, offset: pageToken ? parseInt(pageToken) : 0, owner_ids: [], chat_ids: [], docs_types: [] },
-      }),
-      'searchDocs'
-    );
-    return { items: res.data.docs_entities || [], hasMore: res.data.has_more };
+    // UAT-first (v1.3.16): the suite search API only indexes docs the calling
+    // identity can see. App identity misses everything in the user's personal
+    // space — the 2026-06-06 "search_docs 搜不到个人空间 PDF" report.
+    // Tool args arrive unvalidated — clamp to sane non-negative integers so a
+    // bad offset can't reach Feishu as NaN/negative or corrupt nextOffset
+    // math (Copilot review, PR #115).
+    const offset = Math.max(0, parseInt(pageToken, 10) || 0);
+    const size = Math.max(1, parseInt(pageSize, 10) || 10);
+    const body = { search_key: query, count: size, offset, owner_ids: [], chat_ids: [], docs_types: [] };
+    const res = await this._asUserOrApp({
+      uatPath: '/open-apis/suite/docs-api/search/object',
+      method: 'POST',
+      body,
+      sdkFn: () => this.client.request({ method: 'POST', url: '/open-apis/suite/docs-api/search/object', data: body }),
+      label: 'searchDocs',
+    });
+    const out = { items: res.data.docs_entities || [], hasMore: res.data.has_more, viaUser: !!res._viaUser };
+    // Offset-based cursor — hasMore alone gave callers no way to actually
+    // page forward, and UAT-wide search makes truncation likelier (the hidden
+    // tail may hold the very personal-space doc the user is hunting).
+    // Guard on items.length: an abnormal has_more:true + empty page would
+    // otherwise emit nextOffset === offset and stall a paging loop.
+    if (res.data.has_more && out.items.length > 0) out.nextOffset = offset + out.items.length;
+    if (res._fallbackWarning) out.fallbackWarning = res._fallbackWarning;
+    return out;
   },
 
   async readDoc(documentId) {
@@ -63,6 +80,22 @@ module.exports = {
     return { items: res.data.items || [] };
   },
 
+  // Direct children of a single block — scoped, so it does not inherit the
+  // whole-document 500-block cap of getDocBlocks. Used by createDocTable to map
+  // a table's cells (and each cell's text block) reliably in large documents.
+  async getBlockChildren(documentId, blockId) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}/children`,
+      query: { page_size: '500' },
+      sdkFn: () => this.client.docx.documentBlockChildren.get({
+        path: { document_id: documentId, block_id: blockId },
+        params: { page_size: 500 },
+      }),
+      label: 'getBlockChildren',
+    });
+    return { items: res.data.items || [] };
+  },
+
   async createDocBlock(documentId, parentBlockId, children, index) {
     const data = { children };
     if (index !== undefined) data.index = index;
@@ -79,6 +112,85 @@ module.exports = {
     return { blocks: res.data.children || [], fallbackWarning: res._fallbackWarning || null };
   },
 
+  // Create a Feishu docx table (block_type=31) and optionally fill its cells —
+  // so callers never have to know docx block types. Added after field reports
+  // of agents guessing the table block_type (40 is wrong; 31 table / 32 cell).
+  // Flow:
+  //   1) create the table block with row_size/column_size — Feishu auto-creates
+  //      the table_cell (32) children (row-major) and gives each cell an empty
+  //      text block.
+  //   2) read the table back to map cell_id -> its auto-created text block.
+  //   3) fill: UPDATE each cell's existing text block (clean — no stray empty
+  //      block) when present, else CREATE a text block in the cell.
+  // `cells` is an optional row-major 2D array of plain strings.
+  // Returns { tableBlockId, cells:[[cellId,...],...], rows, columns, filled, viaUser, fallbackWarning }.
+  async createDocTable(documentId, parentBlockId, { rows, columns, cells, columnWidth, headerRow, headerColumn, index } = {}) {
+    rows = Number(rows); columns = Number(columns);
+    if (!Number.isInteger(rows) || !Number.isInteger(columns) || rows < 1 || columns < 1) {
+      throw new Error('createDocTable: rows and columns must be integers >= 1');
+    }
+    const property = { row_size: rows, column_size: columns };
+    if (Array.isArray(columnWidth) && columnWidth.length === columns) property.column_width = columnWidth;
+    if (headerRow) property.header_row = true;
+    if (headerColumn) property.header_column = true;
+    const createBody = { children: [{ block_type: 31, table: { property } }] };
+    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: 'createDocTable',
+    });
+    const tableCreated = (created.data.children || [])[0];
+    const tableBlockId = tableCreated?.block_id;
+    if (!tableBlockId) throw new Error(`createDocTable: no table block_id returned: ${JSON.stringify(created.data).slice(0, 400)}`);
+    const viaUser = !!created._viaUser;
+    const fallbackWarning = created._fallbackWarning || null;
+
+    // Resolve the cell IDs. Prefer the create response; else fetch the table
+    // block's children directly (scoped — NOT the whole-doc getDocBlocks, which
+    // caps at 500 blocks and would silently lose an appended table's cells in a
+    // large document). Fail loud rather than silently dropping requested content.
+    let flatCellIds = tableCreated.table?.cells || tableCreated.children || [];
+    if (flatCellIds.length < rows * columns) {
+      flatCellIds = ((await this.getBlockChildren(documentId, tableBlockId)).items || []).map(b => b.block_id);
+    }
+    if (flatCellIds.length < rows * columns) {
+      throw new Error(`createDocTable: created table ${tableBlockId} but resolved only ${flatCellIds.length}/${rows * columns} cells — aborting fill to avoid silently dropping content.`);
+    }
+    const grid = [];
+    for (let r = 0; r < rows; r++) grid.push(flatCellIds.slice(r * columns, (r + 1) * columns));
+
+    let filled = 0;
+    if (Array.isArray(cells)) {
+      for (let r = 0; r < rows; r++) {
+        for (let c = 0; c < columns; c++) {
+          const content = cells[r] ? cells[r][c] : undefined;
+          if (content === undefined || content === null || content === '') continue;
+          const cellId = grid[r][c];
+          if (!cellId) throw new Error(`createDocTable: missing cell id at row ${r}, col ${c}`);
+          // Each fresh cell auto-creates exactly one empty text block — UPDATE it
+          // (clean) rather than CREATE a second. Scoped per-cell fetch stays
+          // correct regardless of overall document size.
+          const cellChildren = (await this.getBlockChildren(documentId, cellId)).items || [];
+          const textChild = cellChildren.find(b => b.block_type === 2);
+          const elements = { elements: [{ text_run: { content: String(content) } }] };
+          if (textChild) {
+            await this.updateDocBlock(documentId, textChild.block_id, { update_text_elements: elements });
+          } else {
+            await this.createDocBlock(documentId, cellId, [{ block_type: 2, text: elements }]);
+          }
+          filled++;
+        }
+      }
+    }
+    return { tableBlockId, cells: grid, rows, columns, filled, viaUser, fallbackWarning };
+  },
+
   async updateDocBlock(documentId, blockId, updateBody) {
     const res = await this._asUserOrApp({
       uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}`,

package/src/clients/official/drive.js

@@ -8,10 +8,35 @@ module.exports = {
   // --- Drive ---
 
   async listFiles(folderToken, { pageSize = 50, pageToken } = {}) {
-    const params = { page_size: pageSize, folder_token: folderToken || '' };
+    // UAT-first (v1.3.16): the bot identity 403s on personal-space ("我的空间")
+    // folders it was never invited to, which made user-uploaded files (UAT
+    // upload path) undiscoverable — and therefore undeletable, because
+    // manage_drive_file needs a file_token only list_files can provide.
+    // Bot fallback keeps bot-shared folders working. (2026-06-06 user report.)
+    const size = Math.max(1, parseInt(pageSize, 10) || 50);
+    const params = { page_size: size, folder_token: folderToken || '' };
     if (pageToken) params.page_token = pageToken;
-    const res = await this._safeSDKCall(() => this.client.drive.file.list({ params }), 'listFiles');
-    return { items: res.data.files || [], hasMore: res.data.has_more };
+    const query = { page_size: String(size), folder_token: folderToken || '' };
+    if (pageToken) query.page_token = pageToken;
+    const res = await this._asUserOrApp({
+      uatPath: '/open-apis/drive/v1/files',
+      query,
+      sdkFn: () => this.client.drive.file.list({ params }),
+      label: 'listFiles',
+    });
+    const out = { items: res.data.files || [], hasMore: res.data.has_more, viaUser: !!res._viaUser };
+    if (res.data.next_page_token) out.nextPageToken = res.data.next_page_token;
+    if (res._fallbackWarning) out.fallbackWarning = res._fallbackWarning;
+    // Empty + bot path + ROOT listing only: with an empty folder_token the
+    // bot lists its OWN root space (usually empty), not the user's 我的空间 —
+    // that mismatch is the blind spot worth explaining. A specific
+    // folder_token the bot cannot access throws (403) and never reaches here,
+    // and a bot-visible folder that is genuinely empty should stay a bare []
+    // (Copilot review, PR #115).
+    if (out.items.length === 0 && !res._viaUser && !folderToken) {
+      out.scopeHint = 'Empty result via app identity: with an empty folder_token the bot lists its OWN root space, not your 我的空间 — your personal files are invisible to it. Run `npx feishu-user-plugin oauth` so list_files can read your own space via UAT.';
+    }
+    return out;
   },
 
   async createFolder(name, parentToken) {

package/src/clients/official/wiki.js

@@ -28,12 +28,31 @@ module.exports = {
     return out;
   },
 
-  async searchWiki(query) {
-    const res = await this._safeSDKCall(
-      () => this.client.request({ method: 'POST', url: '/open-apis/suite/docs-api/search/object', data: { search_key: query, count: 20, offset: 0, owner_ids: [], chat_ids: [], docs_types: ['wiki'] } }),
-      'searchWiki'
-    );
-    return { items: res.data.docs_entities || [] };
+  async searchWiki(query, { pageSize = 20, offset = 0 } = {}) {
+    // UAT-first (v1.3.16): same blind spot as searchDocs — the suite search
+    // API only indexes entities the calling identity can see, so the app
+    // identity misses wiki nodes in spaces the bot wasn't invited to.
+    // Clamp unvalidated tool args (Copilot review, PR #115).
+    const safeOffset = Math.max(0, parseInt(offset, 10) || 0);
+    const size = Math.max(1, parseInt(pageSize, 10) || 20);
+    const body = { search_key: query, count: size, offset: safeOffset, owner_ids: [], chat_ids: [], docs_types: ['wiki'] };
+    const res = await this._asUserOrApp({
+      uatPath: '/open-apis/suite/docs-api/search/object',
+      method: 'POST',
+      body,
+      sdkFn: () => this.client.request({ method: 'POST', url: '/open-apis/suite/docs-api/search/object', data: body }),
+      label: 'searchWiki',
+    });
+    const out = { items: res.data.docs_entities || [], hasMore: res.data.has_more, viaUser: !!res._viaUser };
+    // The suite search API is offset-based; hand the caller a ready-to-use
+    // cursor so paging doesn't require manual offset math (UAT-wide search
+    // makes truncation likelier — the hidden tail may hold the very
+    // personal-space doc the user is hunting).
+    // Guard on items.length: see searchDocs — prevents a stalled cursor on an
+    // abnormal has_more:true + empty page.
+    if (res.data.has_more && out.items.length > 0) out.nextOffset = safeOffset + out.items.length;
+    if (res._fallbackWarning) out.fallbackWarning = res._fallbackWarning;
+    return out;
   },
 
   // Resolves a wiki node token to its underlying object (docx / sheet / bitable / ...).
@@ -46,8 +65,27 @@ module.exports = {
   // and returns a synthesized node-shaped result so callers don't have to know
   // which ID space they're holding.
   async getWikiNode(nodeToken, _spaceId) {
-    const res = await this._safeSDKCall(() => this.client.wiki.space.getNode({ params: { token: nodeToken } }), 'getNode');
-    return res.data.node;
+    // UAT-first (v1.3.16): bot identity hits permission errors on spaces it
+    // wasn't invited to (same class as listWikiNodes' 131006). The dual-failure
+    // error from _asUserOrApp embeds the Feishu code ("as user: code=953001
+    // ..."), so the obj_token detection regex in tools/wiki.js keeps working.
+    const res = await this._asUserOrApp({
+      uatPath: '/open-apis/wiki/v2/spaces/get_node',
+      query: { token: nodeToken },
+      sdkFn: () => this.client.wiki.space.getNode({ params: { token: nodeToken } }),
+      label: 'getNode',
+    });
+    const node = res.data.node;
+    // Keep the bare-node return shape (resolver.js reads obj_token/obj_type
+    // off it), but attach identity metadata additively so the get_wiki_node
+    // tool surfaces degradation like its 3 sibling discovery reads — without
+    // this, a UAT-revoked → bot fallback would silently swallow the warning
+    // (json() hoists `fallbackWarning` only when it is on the returned object).
+    if (node && typeof node === 'object') {
+      node.viaUser = !!res._viaUser;
+      if (res._fallbackWarning) node.fallbackWarning = res._fallbackWarning;
+    }
+    return node;
   },
 
   async listWikiNodes(spaceId, { parentNodeToken, pageToken } = {}) {

package/src/test-all.js

@@ -322,6 +322,10 @@ async function main() {
 main().catch(console.error).finally(() => {
   // Fixture-based unit test — runs regardless of credential availability
   require('./test-read-doc-markdown').run();
+  require('./test-doc-table').run().catch(e => {
+    console.error('doc-table: FAIL', e);
+    process.exitCode = 1;
+  });
   require('./test-switch-profile').run().catch(e => {
     console.error('switch-profile-e2e: FAIL', e);
     process.exitCode = 1;
@@ -373,6 +377,10 @@ main().catch(console.error).finally(() => {
     console.error('search-messages: FAIL', e);
     process.exitCode = 1;
   });
+  require('./test-uat-read-paths').run().catch(e => {
+    console.error('uat-read-paths: FAIL', e);
+    process.exitCode = 1;
+  });
   require('./test-cli-tool').run();
   require('./test-lark-desktop').run();
   require('./test-display-label');  // standalone — runs on require, exits non-zero on fail

package/src/test-doc-table.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// Unit tests for createDocTable (manage_doc_block create mode F — tables).
+//
+// Guards the payload contract (block_type=31 table, row_size/column_size), the
+// cell-fill behaviour (UPDATE an existing auto-created text block — no stray
+// empty blocks — else CREATE one), and the fail-loud behaviour when the table's
+// cells cannot be resolved (so large docs never silently drop content). Pure
+// unit: the client methods (_asUserOrApp / getBlockChildren / updateDocBlock /
+// createDocBlock) are stubbed, so no network. End-to-end behaviour is verified
+// separately against live Feishu (create doc → table → read back → delete).
+'use strict';
+
+const assert = require('assert');
+const docs = require('./clients/official/docs');
+
+let pass = 0, fail = 0;
+async function ok(name, fn) {
+  try { await fn(); console.log(`  OK  ${name}`); pass++; }
+  catch (e) { console.log(`  FAIL ${name}: ${e.message}`); fail++; }
+}
+
+// Build a stubbed `this` for createDocTable.
+//   cellIds          — the table's cells (row-major)
+//   cellsInCreate    — true: create response carries cell ids; false: forces a
+//                      scoped getBlockChildren(table) lookup
+//   cellHasText      — true: each cell already has an auto text block (UPDATE);
+//                      false: empty cell (CREATE)
+//   resolvableCells  — cell ids that getBlockChildren(table) will return (defaults
+//                      to cellIds); set shorter to exercise fail-loud
+function stub({ cellIds, cellsInCreate = true, cellHasText = true, resolvableCells } = {}) {
+  const calls = { createBody: null, updates: [], creates: [], childFetches: [] };
+  const self = {
+    async _asUserOrApp({ body }) {
+      calls.createBody = body;
+      const tbl = { block_id: 'tbl1' };
+      if (cellsInCreate) tbl.children = cellIds;
+      return { data: { children: [tbl] }, _viaUser: true, _fallbackWarning: null };
+    },
+    async getBlockChildren(documentId, blockId) {
+      calls.childFetches.push(blockId);
+      if (blockId === 'tbl1') {
+        const ids = resolvableCells || cellIds;
+        return { items: ids.map(id => ({ block_id: id, block_type: 32 })) };
+      }
+      // a cell → its auto text block (or none)
+      return { items: cellHasText ? [{ block_id: 't-' + blockId, block_type: 2 }] : [] };
+    },
+    async updateDocBlock(documentId, blockId, body) { calls.updates.push({ blockId, body }); return { block: {} }; },
+    async createDocBlock(documentId, parent, children) { calls.creates.push({ parent, children }); return { blocks: [] }; },
+  };
+  return { self, calls };
+}
+
+async function run() {
+  console.log('=== test-doc-table ===');
+
+  await ok('builds block_type=31 payload + fills by UPDATEing each cell\'s existing text (no stray blocks)', async () => {
+    const { self, calls } = stub({ cellIds: ['c00', 'c01', 'c10', 'c11'], cellsInCreate: true, cellHasText: true });
+    const r = await docs.createDocTable.call(self, 'docX', 'docX', { rows: 2, columns: 2, cells: [['A', 'B'], ['C', 'D']] });
+    const tableBody = calls.createBody.children[0];
+    assert.strictEqual(tableBody.block_type, 31, 'table block_type must be 31 (not 40)');
+    assert.strictEqual(tableBody.table.property.row_size, 2);
+    assert.strictEqual(tableBody.table.property.column_size, 2);
+    assert.deepStrictEqual(r.cells, [['c00', 'c01'], ['c10', 'c11']], 'cells mapped row-major');
+    assert.strictEqual(r.filled, 4);
+    assert.strictEqual(calls.updates.length, 4, 'should UPDATE 4 existing cell text blocks');
+    assert.strictEqual(calls.creates.length, 0, 'should NOT create extra blocks when the cell already has a text block');
+    assert.strictEqual(calls.updates[0].body.update_text_elements.elements[0].text_run.content, 'A');
+    assert.strictEqual(r.viaUser, true);
+  });
+
+  await ok('CREATEs a text block when a cell has no auto text block', async () => {
+    const { self, calls } = stub({ cellIds: ['c0', 'c1'], cellsInCreate: true, cellHasText: false });
+    const r = await docs.createDocTable.call(self, 'd', 'd', { rows: 1, columns: 2, cells: [['X', 'Y']] });
+    assert.strictEqual(r.filled, 2);
+    assert.strictEqual(calls.creates.length, 2, 'should CREATE a text block in each empty cell');
+    assert.strictEqual(calls.updates.length, 0);
+    assert.strictEqual(calls.creates[0].children[0].block_type, 2, 'created child is a text block');
+  });
+
+  await ok('resolves cells via scoped getBlockChildren when the create response lacks them', async () => {
+    const { self, calls } = stub({ cellIds: ['c0', 'c1'], cellsInCreate: false, cellHasText: true });
+    const r = await docs.createDocTable.call(self, 'd', 'd', { rows: 1, columns: 2, cells: [['X', 'Y']] });
+    assert.deepStrictEqual(r.cells, [['c0', 'c1']]);
+    assert.strictEqual(r.filled, 2);
+    assert.ok(calls.childFetches.includes('tbl1'), 'should scope-fetch the table block children when create response lacks cells');
+  });
+
+  await ok('fails loud (throws) when cells cannot be fully resolved — never silently drops content', async () => {
+    // create response lacks cells AND scoped lookup returns too few (e.g. >500-block doc)
+    const { self } = stub({ cellIds: ['c0', 'c1'], cellsInCreate: false, resolvableCells: ['c0'] });
+    let threw = false, msg = '';
+    try { await docs.createDocTable.call(self, 'd', 'd', { rows: 1, columns: 2, cells: [['X', 'Y']] }); }
+    catch (e) { threw = true; msg = e.message; }
+    assert.ok(threw, 'should throw rather than return a low-filled success');
+    assert.ok(/resolved only 1\/2 cells/.test(msg), `error should name the shortfall: ${msg}`);
+  });
+
+  await ok('leaves omitted/blank cells empty and counts only filled', async () => {
+    const { self, calls } = stub({ cellIds: ['c0', 'c1', 'c2', 'c3'], cellsInCreate: true, cellHasText: true });
+    const r = await docs.createDocTable.call(self, 'd', 'd', { rows: 2, columns: 2, cells: [['only', ''], [null, 'here']] });
+    assert.strictEqual(r.filled, 2, 'blank/null cells are skipped');
+    assert.strictEqual(calls.updates.length, 2);
+  });
+
+  await ok('rejects rows/columns < 1', async () => {
+    const { self } = stub({ cellIds: [] });
+    for (const bad of [{ rows: 0, columns: 2 }, { rows: 2, columns: 0 }, { rows: -1, columns: 1 }]) {
+      let threw = false;
+      try { await docs.createDocTable.call(self, 'd', 'd', bad); } catch (_) { threw = true; }
+      assert.ok(threw, `rows/columns ${JSON.stringify(bad)} should throw`);
+    }
+  });
+
+  console.log(`\n=== test-doc-table: ${pass} passed, ${fail} failed ===`);
+  if (fail > 0) process.exit(1);
+}
+
+if (require.main === module) {
+  run().catch((e) => { console.error('test-doc-table harness error:', e); process.exit(1); });
+}
+
+module.exports = { run };

package/src/test-uat-lifecycle.js

@@ -276,6 +276,101 @@ async function run() {
     }
   });
 
+  // --- refreshUAT: benign rotation race must self-heal, not false-revoke ---
+  //
+  // A peer process wins the refresh_token rotation and persists a fresh, VALID
+  // token to disk DURING our refresh round-trip; our now-stale refresh_token
+  // then comes back invalid_grant. refreshUAT must adopt the peer's on-disk
+  // token and recover, instead of throwing uatRevoked (which would push the
+  // user through a needless `npx feishu-user-plugin oauth` re-consent — the
+  // root cause of the "授权操作通知 没撑过一晚上" reports).
+  await ok('refreshUAT: invalid_grant + peer rotated fresh token to disk → adopts & recovers (no false revoke)', async () => {
+    os.homedir = () => fakeHome;
+    const now = Math.floor(Date.now() / 1000);
+    // Disk starts equal to our stale in-memory token so the pre-fetch adopt
+    // checks find nothing newer and we proceed into the refresh fetch.
+    writeCanonical({
+      LARK_USER_ACCESS_TOKEN: 'stale.access',
+      LARK_USER_REFRESH_TOKEN: 'stale.refresh',
+      LARK_UAT_EXPIRES: String(now - 3600),
+    });
+
+    const origFetch = global.fetch;
+    global.fetch = async () => {
+      // The winning peer finishes mid-round-trip: persists a fresh VALID token.
+      writeCanonical({
+        LARK_USER_ACCESS_TOKEN: 'winner.access',
+        LARK_USER_REFRESH_TOKEN: 'winner.refresh',
+        LARK_UAT_EXPIRES: String(now + 7200),
+      });
+      // Our stale refresh_token was rotated away on the Feishu side.
+      return { json: async () => ({ error: 'invalid_grant', error_description: 'refresh_token expired' }) };
+    };
+
+    try {
+      const client = {
+        appId: 'test', appSecret: 'test',
+        _uat: 'stale.access',
+        _uatRefresh: 'stale.refresh',
+        _uatExpires: now - 3600,
+      };
+      let thrown = null, ret = null;
+      try { ret = await uat.refreshUAT(client); } catch (e) { thrown = e; }
+      assert.ok(!thrown, `should recover, not throw; got: ${thrown && thrown.message}`);
+      assert.strictEqual(ret, 'winner.access', 'should return the peer-rotated access token');
+      assert.strictEqual(client._uatRefresh, 'winner.refresh', 'should adopt the peer-rotated refresh_token');
+    } finally {
+      global.fetch = origFetch;
+      os.homedir = origHomedir;
+    }
+  });
+
+  // Codex review (PR #111) edge: a peer in-process refresh / credentials-monitor
+  // hot-reloads THIS client in memory (and persists to disk) WHILE our refresh
+  // request — carrying the now-stale token — is still in flight. Because we
+  // snapshot the sent token before awaiting and gate recovery on client state
+  // (not adoptPersistedUATIfNewer's return value), we must still recover instead
+  // of false-revoking. With the pre-fix code (post-await capture) this throws.
+  await ok('refreshUAT: invalid_grant after mid-flight hot-reload to a fresh token → recovers (no false revoke)', async () => {
+    os.homedir = () => fakeHome;
+    const now = Math.floor(Date.now() / 1000);
+    // Disk starts stale so the pre-fetch adopt checks proceed into the fetch.
+    writeCanonical({
+      LARK_USER_ACCESS_TOKEN: 'stale.access',
+      LARK_USER_REFRESH_TOKEN: 'stale.refresh',
+      LARK_UAT_EXPIRES: String(now - 3600),
+    });
+    const client = {
+      appId: 'test', appSecret: 'test',
+      _uat: 'stale.access', _uatRefresh: 'stale.refresh', _uatExpires: now - 3600,
+    };
+
+    const origFetch = global.fetch;
+    global.fetch = async () => {
+      // Concurrent winner finishes mid-flight: persists rotated token to disk
+      // AND a hot-reload updates this very client in memory.
+      writeCanonical({
+        LARK_USER_ACCESS_TOKEN: 'winner.access',
+        LARK_USER_REFRESH_TOKEN: 'winner.refresh',
+        LARK_UAT_EXPIRES: String(now + 7200),
+      });
+      client._uat = 'winner.access';
+      client._uatRefresh = 'winner.refresh';
+      client._uatExpires = now + 7200;
+      return { json: async () => ({ error: 'invalid_grant', error_description: 'refresh_token expired' }) };
+    };
+
+    try {
+      let thrown = null, ret = null;
+      try { ret = await uat.refreshUAT(client); } catch (e) { thrown = e; }
+      assert.ok(!thrown, `should recover, not throw; got: ${thrown && thrown.message}`);
+      assert.strictEqual(ret, 'winner.access', 'should recover the winner token despite mid-flight hot-reload');
+    } finally {
+      global.fetch = origFetch;
+      os.homedir = origHomedir;
+    }
+  });
+
   // identity-state.js redact-regex regression guard. Exercises the actual
   // regex on `_classifyUatFailure` path that the previous "no dead.refresh"
   // assertion in test #14 did NOT cover (the invalid_grant message is

package/src/test-uat-read-paths.js

@@ -0,0 +1,313 @@
+// src/test-uat-read-paths.js — verify discovery-read paths are UAT-first.
+//
+// Background (2026-06-06 user report): upload_drive_file goes UAT (file owned
+// by the user), but list_files went app-token-only → bot gets 403 on personal
+// space folders ("我的空间"), so uploaded files were undiscoverable and thus
+// undeletable (manage_drive_file needs a file_token the user can't obtain).
+// search_docs had the same blind spot (personal-space files not indexed for
+// the bot identity). searchWiki / getWikiNode shared the app-only pattern.
+//
+// Fix: route listFiles / searchDocs / searchWiki / getWikiNode through
+// _asUserOrApp (UAT-first, bot fallback + fallbackWarning), matching
+// listWikiSpaces / listWikiNodes which were already UAT-first.
+//
+// Tests stub `this._asUserOrApp` at the mixin level (methods are mixed into
+// LarkOfficialClient.prototype; binding them to a fake `this` is the
+// supported seam — same approach as test-via-user.js's fakeCtx).
+
+'use strict';
+
+const assert = require('node:assert/strict');
+
+const driveMixin = require('./clients/official/drive');
+const docsMixin = require('./clients/official/docs');
+const wikiMixin = require('./clients/official/wiki');
+
+// fake `this` for mixin methods. Records _asUserOrApp / _safeSDKCall calls.
+// uatResult is what _asUserOrApp resolves to (shape: legacy asUserOrApp
+// contract — data object with _viaUser + optional _fallbackWarning).
+function fakeClient({ uatResult, sdkResult }) {
+  const calls = { asUserOrApp: [], safeSDKCall: [] };
+  return {
+    calls,
+    async _asUserOrApp(opts) {
+      calls.asUserOrApp.push(opts);
+      return uatResult;
+    },
+    async _safeSDKCall(fn, label) {
+      calls.safeSDKCall.push(label);
+      // Default shape covers all four legacy call sites so pre-fix code fails
+      // on the routing assertions (clean RED) instead of a TypeError here.
+      return sdkResult || { code: 0, data: { files: [], has_more: false, docs_entities: [], node: {} } };
+    },
+    // SDK surface — only reached via the sdkFn closures, which these tests
+    // never execute (the _asUserOrApp stub doesn't call sdkFn).
+    client: {
+      drive: { file: { list: async () => { throw new Error('sdkFn should not run in these tests'); } } },
+      wiki: { space: { getNode: async () => { throw new Error('sdkFn should not run in these tests'); } } },
+      request: async () => { throw new Error('sdkFn should not run in these tests'); },
+    },
+  };
+}
+
+async function run() {
+  // --- 1. listFiles is UAT-first via _asUserOrApp ---
+  {
+    const c = fakeClient({
+      uatResult: { code: 0, data: { files: [{ token: 'boxcnX', name: 'a.pdf' }], has_more: false }, _viaUser: true },
+    });
+    const res = await driveMixin.listFiles.call(c, 'fldcnROOT');
+    assert.equal(c.calls.asUserOrApp.length, 1, 'listFiles must route through _asUserOrApp (UAT-first)');
+    assert.equal(c.calls.safeSDKCall.length, 0, 'listFiles must not call _safeSDKCall directly (app-only blind spot)');
+    const opts = c.calls.asUserOrApp[0];
+    assert.equal(opts.uatPath, '/open-apis/drive/v1/files', 'listFiles UAT path');
+    assert.equal(opts.query.folder_token, 'fldcnROOT');
+    assert.ok(opts.sdkFn, 'bot fallback must be preserved');
+    assert.equal(res.viaUser, true, 'viaUser surfaced');
+    assert.equal(res.items.length, 1);
+  }
+
+  // --- 2. listFiles surfaces fallbackWarning + scopeHint on bot path ---
+  {
+    const c = fakeClient({
+      uatResult: { code: 0, data: { files: [], has_more: false }, _viaUser: false, _fallbackWarning: '⚠️ test-warning' },
+    });
+    const res = await driveMixin.listFiles.call(c, '');
+    assert.equal(res.viaUser, false);
+    assert.equal(res.fallbackWarning, '⚠️ test-warning', 'fallbackWarning must surface so ownership blind spot is visible');
+    assert.ok(res.scopeHint && /403|个人|personal|my space|我的空间|scope/i.test(res.scopeHint),
+      'empty bot-path result must carry a scopeHint explaining the personal-space blind spot');
+  }
+
+  // --- 3. listFiles passes pagination through ---
+  {
+    const c = fakeClient({
+      uatResult: { code: 0, data: { files: [], has_more: true, next_page_token: 'NPT' }, _viaUser: true },
+    });
+    const res = await driveMixin.listFiles.call(c, 'fld', { pageSize: 10, pageToken: 'PT' });
+    const opts = c.calls.asUserOrApp[0];
+    assert.equal(String(opts.query.page_size), '10');
+    assert.equal(opts.query.page_token, 'PT');
+    assert.equal(res.nextPageToken, 'NPT', 'next_page_token must surface for pagination');
+  }
+
+  // --- 4. searchDocs is UAT-first ---
+  {
+    const c = fakeClient({
+      uatResult: { code: 0, data: { docs_entities: [{ docs_token: 'boxcnY' }], has_more: false }, _viaUser: true },
+    });
+    const res = await docsMixin.searchDocs.call(c, 'PDF 报告');
+    assert.equal(c.calls.asUserOrApp.length, 1, 'searchDocs must route through _asUserOrApp');
+    const opts = c.calls.asUserOrApp[0];
+    assert.equal(opts.uatPath, '/open-apis/suite/docs-api/search/object');
+    assert.equal(opts.method, 'POST');
+    assert.equal(opts.body.search_key, 'PDF 报告');
+    assert.deepEqual(opts.body.docs_types, [], 'searchDocs searches all types');
+    assert.equal(res.viaUser, true);
+    assert.equal(res.items.length, 1);
+  }
+
+  // --- 5. searchWiki is UAT-first, scoped to wiki ---
+  {
+    const c = fakeClient({
+      uatResult: { code: 0, data: { docs_entities: [] }, _viaUser: false, _fallbackWarning: '⚠️ w' },
+    });
+    const res = await wikiMixin.searchWiki.call(c, 'roadmap');
+    assert.equal(c.calls.asUserOrApp.length, 1, 'searchWiki must route through _asUserOrApp');
+    const opts = c.calls.asUserOrApp[0];
+    assert.equal(opts.uatPath, '/open-apis/suite/docs-api/search/object');
+    assert.deepEqual(opts.body.docs_types, ['wiki'], 'searchWiki restricted to wiki entities');
+    assert.equal(res.viaUser, false);
+    assert.equal(res.fallbackWarning, '⚠️ w');
+  }
+
+  // --- 6. getWikiNode is UAT-first and surfaces viaUser ---
+  {
+    const c = fakeClient({
+      uatResult: { code: 0, data: { node: { node_token: 'wikcnZ', obj_type: 'docx' } }, _viaUser: true },
+    });
+    const node = await wikiMixin.getWikiNode.call(c, 'wikcnZ');
+    assert.equal(c.calls.asUserOrApp.length, 1, 'getWikiNode must route through _asUserOrApp');
+    const opts = c.calls.asUserOrApp[0];
+    assert.equal(opts.uatPath, '/open-apis/wiki/v2/spaces/get_node');
+    assert.equal(opts.query.token, 'wikcnZ');
+    assert.equal(node.node_token, 'wikcnZ');
+    assert.equal(node.viaUser, true, 'getWikiNode must surface viaUser like its 3 sibling reads');
+  }
+
+  // --- 6b. getWikiNode bot fallback must NOT swallow the fallbackWarning ---
+  // The warning lives on the top-level data object from withIdentityFallback,
+  // not on data.node — without explicit copying, a UAT-revoked → bot fallback
+  // silently drops it (caught by multi-agent review of the original commit).
+  {
+    const c = fakeClient({
+      uatResult: { code: 0, data: { node: { node_token: 'wikcnZ', obj_type: 'docx' } }, _viaUser: false, _fallbackWarning: '⚠️ g' },
+    });
+    const node = await wikiMixin.getWikiNode.call(c, 'wikcnZ');
+    assert.equal(node.viaUser, false);
+    assert.equal(node.fallbackWarning, '⚠️ g', 'fallbackWarning must survive onto the node so json() hoists it');
+  }
+
+  // --- 7. get_wiki_node handler still synthesizes for obj_tokens on dual failure ---
+  // withIdentityFallback dual-failure error message embeds the Feishu code
+  // (e.g. "as user: code=953001 ..."). The handler's /95300\d/ detection must
+  // keep matching so search_wiki obj_tokens (docxXXX) still resolve.
+  {
+    const { handlers } = require('./tools/wiki');
+    const err = new Error('getNode failed on both identities. as user: code=953001 msg=node not found. as app: getNode failed (953001): invalid token');
+    const ctx = {
+      getOfficialClient: () => ({
+        getWikiNode: async () => { throw err; },
+      }),
+    };
+    const resp = await handlers.get_wiki_node({ node_token: 'docxabcdef' }, ctx);
+    const body = JSON.parse(resp.content[0].text);
+    assert.equal(body.obj_type, 'docx', 'obj_token synthesis must survive the dual-identity error shape');
+    assert.equal(body.obj_token, 'docxabcdef');
+  }
+
+  // --- 7b. synthesis also survives the LIVE error shape (131005, not 95300x) ---
+  // Real Feishu instances return code=131005 "not found" for non-wiki tokens
+  // (observed in E2E 2026-06-06); only the `node.*not.*found` regex branch
+  // catches it. Pin that branch so a regex edit can't silently regress it.
+  {
+    const { handlers } = require('./tools/wiki');
+    const err = new Error('getNode failed on both identities. as user: code=131005 msg=not found. as app: getNode failed (HTTP 400, code=131005): not found');
+    const ctx = {
+      getOfficialClient: () => ({
+        getWikiNode: async () => { throw err; },
+      }),
+    };
+    const resp = await handlers.get_wiki_node({ node_token: 'bascnabcdef' }, ctx);
+    const body = JSON.parse(resp.content[0].text);
+    assert.equal(body.obj_type, 'bitable', 'live 131005 error shape must still trigger obj_token synthesis');
+    assert.equal(body.obj_token, 'bascnabcdef');
+  }
+
+  // --- 10. search pagination: nextOffset cursor surfaces; params pass through ---
+  {
+    const c = fakeClient({
+      uatResult: { code: 0, data: { docs_entities: [{ t: 1 }, { t: 2 }], has_more: true }, _viaUser: true },
+    });
+    const res = await docsMixin.searchDocs.call(c, 'q', { pageSize: 2, pageToken: '4' });
+    assert.equal(c.calls.asUserOrApp[0].body.offset, 4, 'searchDocs offset passthrough');
+    assert.equal(c.calls.asUserOrApp[0].body.count, 2, 'searchDocs page size passthrough');
+    assert.equal(res.nextOffset, 6, 'searchDocs nextOffset = offset + items returned');
+  }
+  {
+    const c = fakeClient({
+      uatResult: { code: 0, data: { docs_entities: [{ t: 1 }], has_more: true }, _viaUser: true },
+    });
+    const res = await wikiMixin.searchWiki.call(c, 'q', { pageSize: 1, offset: 3 });
+    assert.equal(c.calls.asUserOrApp[0].body.offset, 3, 'searchWiki offset passthrough');
+    assert.equal(c.calls.asUserOrApp[0].body.count, 1, 'searchWiki page size passthrough');
+    assert.equal(res.nextOffset, 4, 'searchWiki nextOffset cursor');
+    assert.equal(res.hasMore, true, 'searchWiki must surface hasMore');
+  }
+  // schema: pagination params exposed on both search tools
+  {
+    const sd = require('./tools/docs').schemas.find(s => s.name === 'search_docs');
+    const sw = require('./tools/wiki').schemas.find(s => s.name === 'search_wiki');
+    assert.ok(sd.inputSchema.properties.page_size && sd.inputSchema.properties.offset, 'search_docs schema pagination');
+    assert.ok(sw.inputSchema.properties.page_size && sw.inputSchema.properties.offset, 'search_wiki schema pagination');
+  }
+
+  // --- 11. unvalidated args are clamped, never reach Feishu as NaN/negative ---
+  // Tool args have no schema validation layer; a bad offset/page_size must be
+  // normalized to sane non-negative integers (Copilot review, PR #115).
+  {
+    const c = fakeClient({
+      uatResult: { code: 0, data: { docs_entities: [{ t: 1 }], has_more: true }, _viaUser: true },
+    });
+    const res = await docsMixin.searchDocs.call(c, 'q', { pageSize: 'abc', pageToken: '-5' });
+    const body = c.calls.asUserOrApp[0].body;
+    assert.equal(body.offset, 0, 'searchDocs negative offset clamps to 0');
+    assert.equal(body.count, 10, 'searchDocs non-numeric page size falls back to default');
+    assert.equal(res.nextOffset, 1, 'nextOffset math stays sane after clamping');
+  }
+  {
+    const c = fakeClient({
+      uatResult: { code: 0, data: { docs_entities: [], has_more: false }, _viaUser: true },
+    });
+    await wikiMixin.searchWiki.call(c, 'q', { pageSize: NaN, offset: 'xyz' });
+    const body = c.calls.asUserOrApp[0].body;
+    assert.equal(body.offset, 0, 'searchWiki non-numeric offset clamps to 0');
+    assert.equal(body.count, 20, 'searchWiki NaN page size falls back to default');
+  }
+
+  // --- 11b. abnormal has_more:true + empty page must NOT emit a stalled cursor ---
+  // nextOffset === offset would loop a paging caller forever (final release
+  // review, v1.3.16). hasMore stays visible; the unusable cursor is withheld.
+  {
+    const c = fakeClient({
+      uatResult: { code: 0, data: { docs_entities: [], has_more: true }, _viaUser: true },
+    });
+    const res = await docsMixin.searchDocs.call(c, 'q', { pageToken: '5' });
+    assert.equal(res.hasMore, true);
+    assert.equal(res.nextOffset, undefined, 'searchDocs empty page must not emit nextOffset === offset');
+  }
+  {
+    const c = fakeClient({
+      uatResult: { code: 0, data: { docs_entities: [], has_more: true }, _viaUser: true },
+    });
+    const res = await wikiMixin.searchWiki.call(c, 'q', { offset: 5 });
+    assert.equal(res.nextOffset, undefined, 'searchWiki empty page must not emit nextOffset === offset');
+  }
+
+  // --- 11c. explicit offset:0 is honored by the handlers (not dropped as falsy) ---
+  {
+    const docsHandlers = require('./tools/docs').handlers;
+    let got;
+    const ctx = { getOfficialClient: () => ({ searchDocs: async (q, opts) => { got = opts; return { items: [] }; } }) };
+    await docsHandlers.search_docs({ query: 'q', offset: 0 }, ctx);
+    assert.equal(got.pageToken, '0', 'search_docs handler must pass explicit offset:0 through');
+  }
+  {
+    const wikiHandlers = require('./tools/wiki').handlers;
+    let got;
+    const ctx = { getOfficialClient: () => ({ searchWiki: async (q, opts) => { got = opts; return { items: [] }; } }) };
+    await wikiHandlers.search_wiki({ query: 'q', offset: 0 }, ctx);
+    assert.equal(got.offset, 0, 'search_wiki handler must pass explicit offset:0 through');
+  }
+
+  // --- 12. scopeHint fires ONLY for empty root listing via bot ---
+  // A bot-visible folder that is genuinely empty must stay a bare [] — the
+  // blind-spot hint is about the bot's OWN root vs the user's 我的空间
+  // (Copilot review, PR #115). 403-on-personal-folder throws and never gets here.
+  {
+    const c = fakeClient({
+      uatResult: { code: 0, data: { files: [], has_more: false }, _viaUser: false },
+    });
+    const res = await driveMixin.listFiles.call(c, 'fldcnSharedEmpty');
+    assert.equal(res.scopeHint, undefined, 'empty bot-visible folder must NOT carry the root blind-spot hint');
+  }
+
+  // --- 8. list_files tool schema exposes pagination + UAT-first semantics ---
+  {
+    const { schemas } = require('./tools/drive');
+    const lf = schemas.find(s => s.name === 'list_files');
+    assert.ok(lf.inputSchema.properties.page_size, 'list_files schema: page_size');
+    assert.ok(lf.inputSchema.properties.page_token, 'list_files schema: page_token');
+    assert.ok(/UAT/i.test(lf.description), 'list_files description must state UAT-first routing');
+  }
+
+  // --- 9. list_files handler passes pagination args through ---
+  {
+    const { handlers } = require('./tools/drive');
+    let got;
+    const ctx = {
+      getOfficialClient: () => ({
+        listFiles: async (folderToken, opts) => { got = { folderToken, opts }; return { items: [], viaUser: true }; },
+      }),
+    };
+    await handlers.list_files({ folder_token: 'fldX', page_size: 25, page_token: 'PT2' }, ctx);
+    assert.equal(got.folderToken, 'fldX');
+    assert.equal(got.opts.pageSize, 25);
+    assert.equal(got.opts.pageToken, 'PT2');
+  }
+
+  console.log('uat-read-paths.js: PASS');
+}
+
+if (require.main === module) run().catch(e => { console.error(e); process.exit(1); });
+module.exports = { run };

package/src/tools/docs.js

@@ -9,10 +9,14 @@ const { text, json } = require('./_registry');
 const schemas = [
   {
     name: 'search_docs',
-    description: '[Official API] Search Feishu documents by keyword.',
+    description: '[Official API] Search Feishu documents by keyword. UAT-first with app fallback: with user identity (UAT) the search covers docs visible to YOU, including your personal space; via bot it only covers docs shared with the bot. Response carries viaUser; when hasMore is true, pass the returned nextOffset back as offset to page forward.',
     inputSchema: {
       type: 'object',
-      properties: { query: { type: 'string', description: 'Search keyword' } },
+      properties: {
+        query: { type: 'string', description: 'Search keyword' },
+        page_size: { type: 'number', description: 'Max results per page (default 10)' },
+        offset: { type: 'number', description: 'Pagination offset from a previous nextOffset' },
+      },
       required: ['query'],
     },
   },
@@ -52,7 +56,7 @@ const schemas = [
   },
   {
     name: 'manage_doc_block',
-    description: '[Official API] Manage content blocks in a document. Single tool replaces v1.3.6 create_doc_block / update_doc_block / delete_doc_blocks.\n  action=create — five modes:\n    (A) Generic — pass `children` array (e.g. [{block_type:2, text:{...}}]).\n    (B) Image from local file — pass `image_path`; plugin uploads and patches.\n    (C) Image from token — pass `image_token` (already uploaded).\n    (D) File attachment from local file — pass `file_path`; plugin handles VIEW-wrap + replace_file.\n    (E) File from token — pass `file_token`.\n  action=update — generic (pass `update_body`), image-replace (pass `image_token`), or file-replace (pass `file_token`).\n  action=delete — pass `parent_block_id` + `start_index` + `end_index` (range delete).\n`document_id` accepts native ID, wiki node token, or Feishu URL.',
+    description: '[Official API] Manage content blocks in a document. Single tool replaces v1.3.6 create_doc_block / update_doc_block / delete_doc_blocks.\n  action=create — six modes (pass exactly ONE):\n    (A) Generic — pass `children` array (e.g. [{block_type:2, text:{...}}]).\n    (B) Image from local file — pass `image_path`; plugin uploads and patches.\n    (C) Image from token — pass `image_token` (already uploaded).\n    (D) File attachment from local file — pass `file_path`; plugin handles VIEW-wrap + replace_file.\n    (E) File from token — pass `file_token`.\n    (F) Table — pass `table={rows,columns,cells?}`; plugin creates a block_type=31 table (Feishu auto-makes the block_type=32 cells) and fills each provided cell. USE THIS for tables — do NOT hand-build table blocks via `children` (the table block_type is 31, NOT 40; getting it wrong returns invalid_param).\n  action=update — generic (pass `update_body`), image-replace (pass `image_token`), or file-replace (pass `file_token`).\n  action=delete — pass `parent_block_id` + `start_index` + `end_index` (range delete).\n`document_id` accepts native ID, wiki node token, or Feishu URL.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -69,6 +73,7 @@ const schemas = [
         file_path: { type: 'string', description: 'Local file path — create mode D (mutually exclusive with other create modes).' },
         file_token: { type: 'string', description: 'Pre-uploaded docx file token — create mode E, or update file-replace.' },
         update_body: { type: 'object', description: 'Generic update payload for action=update. E.g. {update_text_elements:{elements:[{text_run:{content:"new text"}}]}}.' },
+        table: { type: 'object', description: 'Create a table — create mode F (mutually exclusive with other create modes). Shape: {rows:int>=1, columns:int>=1, cells?:string[][] (row-major plain text; omit/empty-string to leave a cell blank), column_width?:int[] (px, length=columns), header_row?:bool, header_column?:bool}. The plugin creates a block_type=31 table, lets Feishu auto-create the cells, and fills each provided cell by updating its text — you never specify block types. Returns {tableBlockId, cells:[[cellId,...]] (row-major grid), filled}. Example: {"rows":2,"columns":2,"cells":[["Name","Role"],["Ann","PM"]]}.' },
       },
       required: ['action', 'document_id'],
     },
@@ -94,7 +99,10 @@ function need(arg, name, action) {
 
 const handlers = {
   async search_docs(args, ctx) {
-    return json(await ctx.getOfficialClient().searchDocs(args.query));
+    const opts = {};
+    if (args.page_size) opts.pageSize = args.page_size;
+    if (args.offset !== undefined) opts.pageToken = String(args.offset);
+    return json(await ctx.getOfficialClient().searchDocs(args.query, opts));
   },
   async read_doc(args, ctx) {
     return json(await ctx.getOfficialClient().readDoc(await ctx.resolveDocId(args.document_id)));
@@ -121,8 +129,16 @@ const handlers = {
     switch (args.action) {
       case 'create': {
         need(args.parent_block_id, 'parent_block_id', 'create');
-        const modes = [args.children, args.image_path, args.image_token, args.file_path, args.file_token].filter(Boolean);
-        if (modes.length > 1) return text('manage_doc_block(create): pass exactly ONE of children / image_path / image_token / file_path / file_token.');
+        const modes = [args.children, args.image_path, args.image_token, args.file_path, args.file_token, args.table].filter(Boolean);
+        if (modes.length > 1) return text('manage_doc_block(create): pass exactly ONE of children / image_path / image_token / file_path / file_token / table.');
+        if (args.table) {
+          const t = args.table;
+          return json(await official.createDocTable(docId, args.parent_block_id, {
+            rows: t.rows, columns: t.columns, cells: t.cells,
+            columnWidth: t.column_width, headerRow: t.header_row, headerColumn: t.header_column,
+            index: args.index,
+          }));
+        }
         if (args.image_path || args.image_token) {
           const r = await official.createDocBlockWithImage(docId, args.parent_block_id, {
             imagePath: args.image_path,
@@ -139,7 +155,7 @@ const handlers = {
           });
           return json(r);
         }
-        if (!args.children) return text('manage_doc_block(create): children, image_path, image_token, file_path, or file_token is required.');
+        if (!args.children) return text('manage_doc_block(create): children, image_path, image_token, file_path, file_token, or table is required.');
         return json(await official.createDocBlock(docId, args.parent_block_id, args.children, args.index));
       }
       case 'update': {

package/src/tools/drive.js

@@ -9,10 +9,14 @@ const { text, json } = require('./_registry');
 const schemas = [
   {
     name: 'list_files',
-    description: '[Official API] List files in a Drive folder.',
+    description: '[Official API] List files in a Drive folder. UAT-first with app fallback: with user identity (UAT), empty folder_token lists YOUR personal-space ("我的空间") root; via bot it can only see folders shared with the bot (personal-space folders return 403). Response carries viaUser so you know whose view you got. Use the returned file token with manage_drive_file to copy/move/delete.',
     inputSchema: {
       type: 'object',
-      properties: { folder_token: { type: 'string', description: 'Folder token (empty for root)' } },
+      properties: {
+        folder_token: { type: 'string', description: 'Folder token (empty for root — your 我的空间 root when UAT is configured)' },
+        page_size: { type: 'number', description: 'Max files per page (default 50)' },
+        page_token: { type: 'string', description: 'Pagination token from a previous nextPageToken' },
+      },
     },
   },
   {
@@ -66,7 +70,10 @@ function need(arg, name, action) {
 
 const handlers = {
   async list_files(args, ctx) {
-    return json(await ctx.getOfficialClient().listFiles(args.folder_token));
+    const opts = {};
+    if (args.page_size) opts.pageSize = args.page_size;
+    if (args.page_token) opts.pageToken = args.page_token;
+    return json(await ctx.getOfficialClient().listFiles(args.folder_token, opts));
   },
   async create_folder(args, ctx) {
     const r = await ctx.getOfficialClient().createFolder(args.name, args.parent_token);

package/src/tools/wiki.js

@@ -10,10 +10,14 @@ const schemas = [
   },
   {
     name: 'search_wiki',
-    description: '[Official API] Search Wiki nodes by keyword.',
+    description: '[Official API] Search Wiki nodes by keyword. UAT-first with app fallback: with user identity (UAT) the search covers wiki spaces visible to YOU; via bot it only covers spaces the bot was invited to. Response carries viaUser; when hasMore is true, pass the returned nextOffset back as offset to page forward.',
     inputSchema: {
       type: 'object',
-      properties: { query: { type: 'string', description: 'Search keyword' } },
+      properties: {
+        query: { type: 'string', description: 'Search keyword' },
+        page_size: { type: 'number', description: 'Max results per page (default 20)' },
+        offset: { type: 'number', description: 'Pagination offset from a previous nextOffset' },
+      },
       required: ['query'],
     },
   },
@@ -119,7 +123,10 @@ const handlers = {
     return json(await ctx.getOfficialClient().listWikiSpaces());
   },
   async search_wiki(args, ctx) {
-    return json(await ctx.getOfficialClient().searchWiki(args.query));
+    const opts = {};
+    if (args.page_size) opts.pageSize = args.page_size;
+    if (args.offset !== undefined) opts.offset = args.offset;
+    return json(await ctx.getOfficialClient().searchWiki(args.query, opts));
   },
   async list_wiki_nodes(args, ctx) {
     return json(await ctx.getOfficialClient().listWikiNodes(args.space_id, { parentNodeToken: args.parent_node_token }));