feishu-user-plugin 1.3.15 → 1.3.16

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.15",
+  "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.15",
+  "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.15",
+  "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,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.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。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "mcpName": "io.github.EthanQC/feishu-user-plugin",
-  "version": "1.3.15",
+  "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.15"
-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.15: manage_doc_block gains a table create mode — agents stop guessing the table block_type (tables are 31, not 40); the plugin builds the block_type=31 table, fills each cell by updating its auto-created text block (no stray empty blocks), resolves cells scoped (no whole-doc 500-block cap) and fails loud rather than silently dropping content. UAT refresh now self-heals a benign refresh_token rotation race: on invalid_grant it re-reads disk and adopts a peer's freshly-persisted valid token (snapshotting the sent token pre-await for the in-process hot-reload case) instead of false-flipping to UAT_REVOKED and pushing the user through a needless oauth re-consent."
+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/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/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) {

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

@@ -377,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-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'],
     },
   },
@@ -95,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)));

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 }));