feishu-user-plugin 1.3.15 → 1.3.17

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/bitable.js

@@ -106,6 +106,7 @@ const schemas = [
         filter: { type: 'object', description: 'Filter conditions (search only, optional)' },
         sort: { type: 'array', description: 'Sort conditions (search only, optional)' },
         page_size: { type: 'number', description: 'Results per page (search only, default 20)' },
+        page_token: { type: 'string', description: 'Pagination cursor (search only) — pass the pageToken from a previous response to fetch the next page when hasMore is true.' },
       },
       required: ['action', 'app_token', 'table_id'],
     },
@@ -221,7 +222,7 @@ const handlers = {
     switch (args.action) {
       case 'search':
         return json(await c.searchBitableRecords(appToken, args.table_id, {
-          filter: args.filter, sort: args.sort, pageSize: args.page_size,
+          filter: args.filter, sort: args.sort, pageSize: args.page_size, pageToken: args.page_token,
         }));
       case 'get': {
         need(args.record_id, 'record_id', 'get');

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'],
     },
   },
@@ -27,11 +31,13 @@ const schemas = [
   },
   {
     name: 'get_doc_blocks',
-    description: '[Official API] Get structured block tree of a document. Returns block types, content, and hierarchy for precise document analysis.',
+    description: '[Official API] Get structured block tree of a document. Returns block types, content, and hierarchy for precise document analysis. Follows pagination internally and returns ALL blocks by default — hasMore:false in the response guarantees the complete tree (pre-v1.3.17 silently capped at 500 blocks). For very large docs, pass max_blocks to bound one call (rounded up to 500/page granularity) and page forward by passing the returned nextPageToken back as page_token; a bounded response carries truncated:true + hasMore:true so partial output is never silent.',
     inputSchema: {
       type: 'object',
       properties: {
         document_id: { type: 'string', description: 'Document ID (from search_docs or create_doc)' },
+        page_token: { type: 'string', description: 'Resume cursor — pass the nextPageToken from a previous truncated response to fetch the next slice.' },
+        max_blocks: { type: 'number', description: 'Soft cap on blocks returned in this call (rounded up to page granularity of 500). Omit to fetch the entire document.' },
       },
       required: ['document_id'],
     },
@@ -52,7 +58,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 — 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.',
+    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`). ⚠ `update_text_elements` REPLACES the block\'s ENTIRE elements array — it is a full overwrite, NOT a patch/append. Any element you omit (bold runs, links, prefixes) is permanently lost; to change part of a block, read it first (get_doc_blocks) and resend ALL elements.\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: {
@@ -68,8 +74,8 @@ const schemas = [
         image_token: { type: 'string', description: 'Pre-uploaded docx image token — create mode C, or update image-replace.' },
         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"]]}.' },
+        update_body: { type: 'object', description: 'Generic update payload for action=update. E.g. {update_text_elements:{elements:[{text_run:{content:"new text"}}]}}. ⚠ update_text_elements is a FULL REPLACEMENT of the block\'s elements array (not patch/append) — include every element you want to keep, or the omitted ones are permanently lost.' },
+        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, failedCells?}. Cell fills auto-retry transient Feishu errors with backoff; cells that still fail do NOT abort the call — they are listed in failedCells:[{row,col,cellId,textBlockId?,reason,skipped?}] (0-based row/col) so you can repair each via action=update on its textBlockId (or action=create into its cellId). Example: {"rows":2,"columns":2,"cells":[["Name","Role"],["Ann","PM"]]}.' },
       },
       required: ['action', 'document_id'],
     },
@@ -95,13 +101,21 @@ 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)));
   },
   async get_doc_blocks(args, ctx) {
-    return json(await ctx.getOfficialClient().getDocBlocks(await ctx.resolveDocId(args.document_id)));
+    const opts = {};
+    if (args.page_token) opts.pageToken = args.page_token;
+    // Pass through verbatim — the client clamps to a finite integer >= 1 and
+    // treats anything else as "no cap" (PR #118 review).
+    if (args.max_blocks !== undefined) opts.maxBlocks = args.max_blocks;
+    return json(await ctx.getOfficialClient().getDocBlocks(await ctx.resolveDocId(args.document_id), opts));
   },
   async create_doc(args, ctx) {
     const r = await ctx.getOfficialClient().createDoc(args.title, args.folder_id, {
@@ -126,11 +140,20 @@ const handlers = {
         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, {
+          const r = 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,
-          }));
+          });
+          // Partial fill — lift a repair-oriented warning above the JSON so the
+          // caller cannot mistake a half-filled table for success (json() hoists
+          // fallbackWarning to the top of the rendered response).
+          if (r.failedCells && r.failedCells.length) {
+            const attempted = r.filled + r.failedCells.length;
+            const fillWarn = `⚠ Table ${r.tableBlockId} created, but ${r.failedCells.length}/${attempted} cell(s) could not be filled (transient errors were already retried). See failedCells[] below — repair each with manage_doc_block(action=update, block_id=<textBlockId>, update_body={update_text_elements:...}), or action=create into its cellId when no textBlockId is given.`;
+            r.fallbackWarning = r.fallbackWarning ? `${fillWarn}\n\n${r.fallbackWarning}` : fillWarn;
+          }
+          return json(r);
         }
         if (args.image_path || args.image_token) {
           const r = await official.createDocBlockWithImage(docId, args.parent_block_id, {
@@ -200,7 +223,13 @@ const handlers = {
       return text(`read_doc_markdown: feishu-docx render failed — ${e.message}. Try get_doc_blocks for raw JSON fallback. (feishu-docx version may need upgrading)`);
     }
 
-    return text(_normaliseEmbeds(md));
+    md = _normaliseEmbeds(md);
+    // getDocBlocks paginates to completion, so hasMore only survives a stalled
+    // upstream cursor — still, never let partial output pass as the whole doc.
+    if (result.hasMore) {
+      md += `\n\n[output truncated: rendered ${blocks.length} blocks but the document has more — the block list could not be fetched to completion. Retry, or use get_doc_blocks with page_token to inspect the tail.]`;
+    }
+    return text(md);
   },
 };
 

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/groups.js

@@ -74,7 +74,18 @@ const handlers = {
     if (args.action === 'remove') {
       return json(await official.removeChatMembers(args.chat_id, args.member_ids, memberIdType));
     }
-    return json(await official.addChatMembers(args.chat_id, args.member_ids, memberIdType));
+    const r = await official.addChatMembers(args.chat_id, args.member_ids, memberIdType);
+    // Lift a top warning when any id did NOT actually join — invalid format,
+    // nonexistent user, or stuck behind join-approval. Without it an empty
+    // invalidIds read as "everyone is in" while some never joined.
+    const problems = [];
+    if (r.invalidIds?.length) problems.push(`${r.invalidIds.length} invalid id(s): ${r.invalidIds.join(', ')}`);
+    if (r.notExistedIds?.length) problems.push(`${r.notExistedIds.length} nonexistent user(s): ${r.notExistedIds.join(', ')}`);
+    if (r.pendingApprovalIds?.length) problems.push(`${r.pendingApprovalIds.length} pending group-owner approval (NOT yet in the group): ${r.pendingApprovalIds.join(', ')}`);
+    if (problems.length) {
+      r.fallbackWarning = `⚠ Partial add — ${problems.join('; ')}. The rest joined successfully.`;
+    }
+    return json(r);
   },
 };
 

package/src/tools/im-read.js

@@ -117,6 +117,7 @@ const schemas = [
         end_time: { type: 'string', description: 'End timestamp in seconds (optional)' },
         sort_type: { type: 'string', enum: ['ByCreateTimeDesc', 'ByCreateTimeAsc'], description: 'Sort order (default: ByCreateTimeDesc = newest first)' },
         expand_merge_forward: { type: 'boolean', description: 'Auto-expand merge_forward placeholders into their child messages (default true). Children carry parentMessageId; use that id (not the child id) with download_message_resource (kind=image or file).' },
+        page_token: { type: 'string', description: 'Pagination cursor — pass the pageToken from a previous response to fetch the next (older) page when hasMore is true.' },
       },
       required: ['chat_id'],
     },
@@ -155,6 +156,7 @@ const schemas = [
         end_time: { type: 'string', description: 'End timestamp in seconds (optional)' },
         sort_type: { type: 'string', enum: ['ByCreateTimeDesc', 'ByCreateTimeAsc'], description: 'Sort order (default: ByCreateTimeDesc = newest first)' },
         expand_merge_forward: { type: 'boolean', description: 'Auto-expand merge_forward placeholders into their child messages (default true). Children carry parentMessageId; use that id (not the child id) with download_message_resource (kind=image or file).' },
+        page_token: { type: 'string', description: 'Pagination cursor — pass the pageToken from a previous response to fetch the next (older) page when hasMore is true.' },
         via_user: { type: 'boolean', description: 'v1.3.12 — explicit identity override. `true` skips the bot path and reads directly via UAT (use when the chat is yours / external and you know bot has no access). `false` skips UAT fallback and surfaces the bot error instead of cross-identity hop (use when you specifically want the bot view). Omit for default auto-fallback (bot first, UAT on failure).' },
       },
       required: ['chat_id'],
@@ -230,7 +232,7 @@ const handlers = {
     }
     return json(await official.readMessagesAsUser(chatId, {
       pageSize: args.page_size, startTime: args.start_time, endTime: args.end_time,
-      sortType: args.sort_type,
+      sortType: args.sort_type, pageToken: args.page_token,
       expandMergeForward: args.expand_merge_forward !== false,
     }, uc));
   },
@@ -247,7 +249,7 @@ const handlers = {
     const official = ctx.getOfficialClient();
     const msgOpts = {
       pageSize: args.page_size, startTime: args.start_time, endTime: args.end_time,
-      sortType: args.sort_type,
+      sortType: args.sort_type, pageToken: args.page_token,
       expandMergeForward: args.expand_merge_forward !== false,
     };
     // v1.3.12: via_user opt-in routing override. true=skip bot (UAT only),

package/src/tools/wiki.js

@@ -5,26 +5,31 @@ const { json } = require('./_registry');
 const schemas = [
   {
     name: 'list_wiki_spaces',
-    description: '[Official API] List all accessible Wiki spaces.',
+    description: '[Official API] List all accessible Wiki spaces. Follows pagination internally and returns ALL spaces (pre-v1.3.17 silently capped at 50). If the upstream cursor stalls, the response carries hasMore:true — treat that as a partial list.',
     inputSchema: { type: 'object', properties: {} },
   },
   {
     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'],
     },
   },
   {
     name: 'list_wiki_nodes',
-    description: '[Official API] List nodes in a Wiki space.',
+    description: '[Official API] List nodes in a Wiki space (50 per page). When hasMore is true, pass the returned pageToken back as page_token to fetch the next page. A page may be EMPTY while hasMore is still true (Feishu permission-filters per page) — do not stop at an empty page; keep paging until hasMore is false.',
     inputSchema: {
       type: 'object',
       properties: {
         space_id: { type: 'string', description: 'Wiki space ID' },
         parent_node_token: { type: 'string', description: 'Parent node token (optional)' },
+        page_token: { type: 'string', description: 'Pagination cursor — pass the pageToken from a previous response to fetch the next page.' },
       },
       required: ['space_id'],
     },
@@ -119,10 +124,13 @@ 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 }));
+    return json(await ctx.getOfficialClient().listWikiNodes(args.space_id, { parentNodeToken: args.parent_node_token, pageToken: args.page_token }));
   },
   async create_wiki_node(args, ctx) {
     return json(await ctx.getOfficialClient().createWikiNode(args.space_id, {