feishu-user-plugin 1.3.15 → 1.3.17

package/src/clients/official/docs.js

@@ -6,19 +6,73 @@
 // base.js or mixed in via other domain modules.
 
 const { buildEmptyImageBlock, buildReplaceImagePayload, buildEmptyFileBlock, buildReplaceFilePayload } = require('../../doc-blocks');
+const { classifyError } = require('../../error-codes');
+
+const _sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// Backoff schedule between cell-fill retries (attempts = delays.length + 1).
+// Field report 2026-06-07: rapid-fire docx writes intermittently trip the
+// code=2200 scope-check flake / frequency control — a short pause clears it.
+const CELL_RETRY_DELAYS_MS = [400, 1200];
+
+// Run fn(); retry on transient failures (classifyError → 'retry') after the
+// next backoff delay. Permanent failures propagate immediately. Safe here
+// because every retried operation is idempotent (update_text_elements is a
+// full replacement; getBlockChildren is a read).
+async function _withTransientRetry(fn, delays) {
+  for (let attempt = 0; ; attempt++) {
+    try { return await fn(); }
+    catch (e) {
+      if (attempt >= delays.length || classifyError(e).action !== 'retry') throw e;
+      await _sleep(delays[attempt]);
+    }
+  }
+}
+
+// Structured error for the 3-step media flows (placeholder → upload → PATCH):
+// the placeholder block already exists in the document when step 2/3 fails, so
+// the failure must name it — and carry the uploaded media token when present —
+// or the caller is left hunting for an unexplained empty block with no repair
+// path (2026-06-07 audit).
+function _orphanBlockError(label, documentId, blockId, stage, cause, mediaToken, tokenParam) {
+  const repair = mediaToken
+    ? `re-attach it with manage_doc_block(action=update, document_id=${documentId}, block_id=${blockId}, ${tokenParam}=${mediaToken}) — no need to re-upload`
+    : `retry, or remove the orphan via manage_doc_block(action=delete, document_id=${documentId}) on its parent block`;
+  const err = new Error(`${label}: placeholder block ${blockId} was created but ${stage} failed — ${cause.message}. The empty block remains in the document; ${repair}.`);
+  err.blockId = blockId;
+  if (mediaToken) err.mediaToken = mediaToken;
+  return err;
+}
 
 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) {
@@ -53,14 +107,71 @@ module.exports = {
     return out;
   },
 
-  async getDocBlocks(documentId) {
-    const res = await this._asUserOrApp({
-      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks`,
-      query: { page_size: '500' },
-      sdkFn: () => this.client.docx.documentBlock.list({ path: { document_id: documentId }, params: { page_size: 500 } }),
-      label: 'getDocBlocks',
-    });
-    return { items: res.data.items || [] };
+  // Fetch the document's block tree. Follows page_token pagination until
+  // exhaustion by default — the pre-v1.3.17 single 500-block page silently
+  // truncated large docs (field report 2026-06-07: a ~300KB doc lost everything
+  // past mid-document, with no flag — callers believed the tail blocks were
+  // never created). Pass maxBlocks to bound one call (rounded up to page
+  // granularity) and resume with the returned nextPageToken as pageToken.
+  // Returns { items, total, hasMore, truncated?, nextPageToken?, viaUser, fallbackWarning? }.
+  // hasMore:false guarantees the full tree is in `items`.
+  async getDocBlocks(documentId, { pageToken, maxBlocks } = {}) {
+    // Tool args arrive unvalidated — accept the cap only as a finite integer
+    // >= 1; anything else (0, negatives, NaN, random strings) means "no cap"
+    // so a malformed value can never silently change paging semantics
+    // (Copilot review PR #118; same clamp precedent as searchDocs offset).
+    const cap = Number.isFinite(Number(maxBlocks)) && Number(maxBlocks) >= 1 ? Math.floor(Number(maxBlocks)) : null;
+    const items = [];
+    let token = pageToken || undefined;
+    let viaUser = true;
+    let fallbackWarning = null;
+    let hasMore = false;
+    let nextPageToken;
+    const seenTokens = new Set();
+    // 1000-page backstop (~500k blocks) — a server that keeps minting fresh
+    // tokens must not pin the loop forever. Hitting it reports hasMore:true.
+    const MAX_PAGES = 1000;
+    let page = 0;
+    for (; page < MAX_PAGES; page++) {
+      if (token) seenTokens.add(token);
+      const query = { page_size: '500' };
+      if (token) query.page_token = token;
+      const params = { page_size: 500 };
+      if (token) params.page_token = token;
+      const res = await this._asUserOrApp({
+        uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks`,
+        query,
+        sdkFn: () => this.client.docx.documentBlock.list({ path: { document_id: documentId }, params }),
+        label: 'getDocBlocks',
+      });
+      const pageItems = res.data.items || [];
+      items.push(...pageItems);
+      viaUser = viaUser && !!res._viaUser;
+      if (!fallbackWarning && res._fallbackWarning) fallbackWarning = res._fallbackWarning;
+      hasMore = !!res.data.has_more;
+      if (!hasMore) break;
+      const next = res.data.page_token;
+      if (cap && items.length >= cap) {
+        if (next) nextPageToken = next;
+        break;
+      }
+      // Stall/cycle guards (PR #116 parity): a missing token, an unchanged
+      // token, or one we've already used means paging forward is futile — stop
+      // and WITHHOLD the cursor rather than loop forever. An EMPTY page is NOT
+      // a stop signal on its own: Feishu legitimately returns empty pages with
+      // has_more:true (permission filtering) and real data behind them, so we
+      // keep going as long as the cursor advances; the MAX_PAGES backstop bounds
+      // a pathological always-empty-new-token server.
+      if (!next || next === token || seenTokens.has(next)) break;
+      token = next;
+    }
+    // Backstop exhausted mid-document: `token` is the still-unfetched cursor.
+    if (page >= MAX_PAGES && hasMore && token) nextPageToken = token;
+    const out = { items, total: items.length, hasMore, viaUser };
+    if (hasMore) out.truncated = true;
+    if (nextPageToken) out.nextPageToken = nextPageToken;
+    if (fallbackWarning) out.fallbackWarning = fallbackWarning;
+    return out;
   },
 
   // Direct children of a single block — scoped, so it does not inherit the
@@ -106,8 +217,18 @@ module.exports = {
   //   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 } = {}) {
+  // Cell fills retry transient Feishu errors (code=2200 scope-check flake,
+  // rate limits, 5xx) with backoff; cells that still fail are reported in
+  // `failedCells` [{row,col,cellId,textBlockId?,reason,skipped?}] (0-based)
+  // instead of aborting the whole call — the table block already exists, so
+  // the caller needs the partial-success map to repair, not an opaque throw
+  // (field report 2026-06-07: a 7×3 fill died at row 6 and the caller had to
+  // grep the whole doc for empty cells). After 3 consecutive cell failures the
+  // remaining fills are skipped (marked skipped:true) — a structural error
+  // (revoked perms) would otherwise burn 2 API calls per remaining cell.
+  // `retryDelaysMs` overrides the backoff schedule (tests only).
+  // Returns { tableBlockId, cells:[[cellId,...],...], rows, columns, filled, failedCells?, viaUser, fallbackWarning }.
+  async createDocTable(documentId, parentBlockId, { rows, columns, cells, columnWidth, headerRow, headerColumn, index, retryDelaysMs } = {}) {
     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');
@@ -149,29 +270,58 @@ module.exports = {
     for (let r = 0; r < rows; r++) grid.push(flatCellIds.slice(r * columns, (r + 1) * columns));
 
     let filled = 0;
+    const failedCells = [];
     if (Array.isArray(cells)) {
+      const delays = Array.isArray(retryDelaysMs) ? retryDelaysMs : CELL_RETRY_DELAYS_MS;
+      let consecutiveFailures = 0;
+      let lastReason = '';
       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}`);
+          if (consecutiveFailures >= 3) {
+            failedCells.push({
+              row: r, col: c, cellId, skipped: true,
+              reason: `skipped: aborted after ${consecutiveFailures} consecutive cell failures (last: ${lastReason})`,
+            });
+            continue;
+          }
           // 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 }]);
+          let textBlockId = null;
+          try {
+            await _withTransientRetry(async () => {
+              // Reset per attempt — the cell is re-inspected on every retry, and
+              // a stale id from a prior attempt must not leak into failedCells.
+              textBlockId = null;
+              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) {
+                textBlockId = textChild.block_id;
+                await this.updateDocBlock(documentId, textChild.block_id, { update_text_elements: elements });
+              } else {
+                await this.createDocBlock(documentId, cellId, [{ block_type: 2, text: elements }]);
+              }
+            }, delays);
+            filled++;
+            consecutiveFailures = 0;
+          } catch (e) {
+            consecutiveFailures++;
+            lastReason = e.message;
+            const entry = { row: r, col: c, cellId, reason: e.message };
+            if (textBlockId) entry.textBlockId = textBlockId;
+            failedCells.push(entry);
           }
-          filled++;
         }
       }
     }
-    return { tableBlockId, cells: grid, rows, columns, filled, viaUser, fallbackWarning };
+    const out = { tableBlockId, cells: grid, rows, columns, filled, viaUser, fallbackWarning };
+    if (failedCells.length) out.failedCells = failedCells;
+    return out;
   },
 
   async updateDocBlock(documentId, blockId, updateBody) {
@@ -207,8 +357,12 @@ module.exports = {
   //   1) create empty image placeholder block
   //   2) upload pixels (skipped if caller passes a ready-made imageToken)
   //   3) patch the placeholder with the uploaded token
+  // Steps 2/3 retry transient failures (upload re-send and PATCH full-replace
+  // are both idempotent); a persistent failure throws an error carrying the
+  // placeholder blockId (+ uploaded token when step 2 succeeded) so the caller
+  // can repair instead of orphan-hunting. `retryDelaysMs` is test-only.
   // Returns { blockId, imageToken, viaUser }.
-  async createDocBlockWithImage(documentId, parentBlockId, { imagePath, imageToken, index } = {}) {
+  async createDocBlockWithImage(documentId, parentBlockId, { imagePath, imageToken, index, retryDelaysMs } = {}) {
     if (!imagePath && !imageToken) {
       throw new Error('createDocBlockWithImage: either imagePath or imageToken is required');
     }
@@ -231,28 +385,39 @@ module.exports = {
     const blockId = newBlock?.block_id;
     if (!blockId) throw new Error(`createDocBlockWithImage: placeholder creation returned no block_id: ${JSON.stringify(created.data).slice(0, 400)}`);
 
-    // Step 2 — upload (if needed).
+    // Step 2 — upload (if needed), with transient retry.
+    const delays = Array.isArray(retryDelaysMs) ? retryDelaysMs : CELL_RETRY_DELAYS_MS;
     let finalToken = imageToken;
     let viaUser = !!created._viaUser;
     let fallbackWarning = created._fallbackWarning || null;
     if (!finalToken) {
-      const uploaded = await this.uploadMedia(imagePath, blockId, 'docx_image');
+      let uploaded;
+      try {
+        uploaded = await _withTransientRetry(() => this.uploadMedia(imagePath, blockId, 'docx_image'), delays);
+      } catch (e) {
+        throw _orphanBlockError('createDocBlockWithImage', documentId, blockId, 'image upload', e, null);
+      }
       finalToken = uploaded.fileToken;
       viaUser = viaUser && uploaded.viaUser; // true iff both steps went via user
     }
 
-    // Step 3 — attach token to the placeholder via PATCH replace_image.
+    // Step 3 — attach token to the placeholder via PATCH replace_image
+    // (idempotent full replace), with transient retry.
     const patch = buildReplaceImagePayload(finalToken);
-    await this._asUserOrApp({
-      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}`,
-      method: 'PATCH',
-      body: patch,
-      sdkFn: () => this.client.docx.documentBlock.patch({
-        path: { document_id: documentId, block_id: blockId },
-        data: patch,
-      }),
-      label: 'createDocBlockWithImage.replaceImage',
-    });
+    try {
+      await _withTransientRetry(() => this._asUserOrApp({
+        uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}`,
+        method: 'PATCH',
+        body: patch,
+        sdkFn: () => this.client.docx.documentBlock.patch({
+          path: { document_id: documentId, block_id: blockId },
+          data: patch,
+        }),
+        label: 'createDocBlockWithImage.replaceImage',
+      }), delays);
+    } catch (e) {
+      throw _orphanBlockError('createDocBlockWithImage', documentId, blockId, 'replace_image PATCH', e, finalToken, 'image_token');
+    }
 
     return { blockId, imageToken: finalToken, viaUser, fallbackWarning };
   },
@@ -279,8 +444,11 @@ module.exports = {
   //   1) create empty file placeholder block
   //   2) upload the binary via uploadMedia(parent_type=docx_file)
   //   3) PATCH with replace_file.token to attach
+  // Steps 2/3 retry transient failures and a persistent failure throws an
+  // error carrying the placeholder blockId (+ uploaded token when step 2
+  // succeeded) — mirrors createDocBlockWithImage. `retryDelaysMs` is test-only.
   // Returns { blockId, fileToken, viaUser, fallbackWarning }.
-  async createDocBlockWithFile(documentId, parentBlockId, { filePath, fileToken, index } = {}) {
+  async createDocBlockWithFile(documentId, parentBlockId, { filePath, fileToken, index, retryDelaysMs } = {}) {
     if (!filePath && !fileToken) {
       throw new Error('createDocBlockWithFile: either filePath or fileToken is required');
     }
@@ -315,26 +483,36 @@ module.exports = {
       blockId = inner;
     }
 
+    const delays = Array.isArray(retryDelaysMs) ? retryDelaysMs : CELL_RETRY_DELAYS_MS;
     let finalToken = fileToken;
     let viaUser = !!created._viaUser;
     let fallbackWarning = created._fallbackWarning || null;
     if (!finalToken) {
-      const uploaded = await this.uploadMedia(filePath, blockId, 'docx_file');
+      let uploaded;
+      try {
+        uploaded = await _withTransientRetry(() => this.uploadMedia(filePath, blockId, 'docx_file'), delays);
+      } catch (e) {
+        throw _orphanBlockError('createDocBlockWithFile', documentId, blockId, 'file upload', e, null);
+      }
       finalToken = uploaded.fileToken;
       viaUser = viaUser && uploaded.viaUser;
     }
 
     const patch = buildReplaceFilePayload(finalToken);
-    await this._asUserOrApp({
-      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}`,
-      method: 'PATCH',
-      body: patch,
-      sdkFn: () => this.client.docx.documentBlock.patch({
-        path: { document_id: documentId, block_id: blockId },
-        data: patch,
-      }),
-      label: 'createDocBlockWithFile.replaceFile',
-    });
+    try {
+      await _withTransientRetry(() => this._asUserOrApp({
+        uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}`,
+        method: 'PATCH',
+        body: patch,
+        sdkFn: () => this.client.docx.documentBlock.patch({
+          path: { document_id: documentId, block_id: blockId },
+          data: patch,
+        }),
+        label: 'createDocBlockWithFile.replaceFile',
+      }), delays);
+    } catch (e) {
+      throw _orphanBlockError('createDocBlockWithFile', documentId, blockId, 'replace_file PATCH', e, finalToken, 'file_token');
+    }
 
     return { blockId, viewBlockId: outerBlockId !== blockId ? outerBlockId : undefined, fileToken: finalToken, viaUser, fallbackWarning };
   },
@@ -360,15 +538,11 @@ module.exports = {
       // None matched directly; return the first as best-effort
       return childIds[0];
     }
-    // Fallback: list all blocks and find a 23 whose parent_id is the view block
+    // Fallback: list all blocks and find a 23 whose parent_id is the view block.
+    // Uses getDocBlocks (paginates past 500 blocks) — a single unpaged list
+    // would miss the freshly appended view block in a large document.
     try {
-      const res = await this._asUserOrApp({
-        uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks`,
-        method: 'GET',
-        sdkFn: () => this.client.docx.documentBlock.list({ path: { document_id: documentId } }),
-        label: '_findFileChildOf.list',
-      });
-      const items = res?.data?.items || [];
+      const { items } = await this.getDocBlocks(documentId);
       const match = items.find(b => b.block_type === 23 && b.parent_id === viewBlockId);
       return match?.block_id || null;
     } catch (_) {

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

@@ -51,7 +51,14 @@ module.exports = {
       }),
       'addChatMembers'
     );
-    return { invalidIds: res.data.invalid_id_list || [] };
+    // Feishu reports three partial-failure buckets on batch add (2026-06-07
+    // audit) — swallowing not_existed/pending_approval made a half-failed add
+    // read as full success (members "in the group" who never joined).
+    return {
+      invalidIds: res.data.invalid_id_list || [],
+      notExistedIds: res.data.not_existed_id_list || [],
+      pendingApprovalIds: res.data.pending_approval_id_list || [],
+    };
   },
 
   async removeChatMembers(chatId, userIds, memberIdType = 'open_id') {

package/src/clients/official/wiki.js

@@ -11,29 +11,81 @@ module.exports = {
     // Try UAT first — most users access only their own / team Wiki spaces
     // which the bot may not have been invited to. Falling back to app keeps
     // the bot-shared-spaces case working too.
-    const res = await this._asUserOrApp({
-      uatPath: '/open-apis/wiki/v2/spaces?page_size=50',
-      method: 'GET',
-      sdkFn: () => this.client.wiki.space.list({ params: { page_size: 50 } }),
-      label: 'listSpaces',
-    });
-    const items = res.data.items || [];
-    const out = { items, viaUser: !!res._viaUser };
-    if (res._fallbackWarning) out.fallbackWarning = res._fallbackWarning;
+    //
+    // Follows page_token pagination to completion (2026-06-07 audit): the
+    // endpoint pages at 50/page and the pre-fix single call silently dropped
+    // every space past the first page with no hasMore flag — spaces beyond
+    // #50 were unreachable (their space_id could never be discovered).
+    const items = [];
+    let token;
+    let viaUser = true;
+    let fallbackWarning = null;
+    let hasMore = false;
+    const seenTokens = new Set();
+    for (let page = 0; page < 200; page++) {
+      if (token) seenTokens.add(token);
+      const query = { page_size: '50' };
+      if (token) query.page_token = token;
+      const params = { page_size: 50 };
+      if (token) params.page_token = token;
+      const res = await this._asUserOrApp({
+        uatPath: '/open-apis/wiki/v2/spaces',
+        method: 'GET',
+        query,
+        sdkFn: () => this.client.wiki.space.list({ params }),
+        label: 'listSpaces',
+      });
+      const pageItems = res.data.items || [];
+      items.push(...pageItems);
+      viaUser = viaUser && !!res._viaUser;
+      if (!fallbackWarning && res._fallbackWarning) fallbackWarning = res._fallbackWarning;
+      hasMore = !!res.data.has_more;
+      if (!hasMore) break;
+      const next = res.data.page_token;
+      // Stall/cycle guards (getDocBlocks parity) — never loop on a server that
+      // drops or repeats the cursor. An empty page is NOT a stop signal: the
+      // Feishu wiki endpoints document empty pages with has_more:true under
+      // permission filtering, with real spaces behind them — keep paging while
+      // the cursor advances; the 200-page backstop bounds a pathological server.
+      if (!next || next === token || seenTokens.has(next)) break;
+      token = next;
+    }
+    const out = { items, viaUser };
+    if (hasMore) out.hasMore = true; // stalled upstream cursor — incompleteness stays visible
+    if (fallbackWarning) out.fallbackWarning = fallbackWarning;
     // Empty + bot path means scope is missing; surface a clear hint instead
     // of silently returning nothing.
-    if (items.length === 0 && !res._viaUser) {
+    if (items.length === 0 && !viaUser) {
       out.scopeHint = 'No spaces returned via app — the bot likely lacks `wiki:wiki:readonly` scope, or has not been invited to any Wiki space. Run `npx feishu-user-plugin oauth` and ensure the wiki scope is granted; or invite the bot to the target Wiki space.';
     }
     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 +98,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 } = {}) {
@@ -66,7 +137,11 @@ module.exports = {
       sdkFn: () => this.client.wiki.spaceNode.list({ path: { space_id: spaceId }, params: sdkParams }),
       label: 'listWikiNodes',
     });
-    return { items: res.data.items || [], hasMore: res.data.has_more, viaUser: !!res._viaUser };
+    // pageToken accompanies hasMore (2026-06-07 audit) — hasMore without the
+    // resume cursor stranded callers at the first 50 nodes forever.
+    const out = { items: res.data.items || [], hasMore: res.data.has_more, viaUser: !!res._viaUser };
+    if (res.data.page_token) out.pageToken = res.data.page_token;
+    return out;
   },
 
   // --- Wiki write (v1.3.7) ---

package/src/error-codes.js

@@ -49,6 +49,13 @@ const FAILURE_MAP = {
   1254301: { action: 'retry', reason: 'upload_transient' },
   1254400: { action: 'retry', reason: 'upload_transient' },
 
+  // docx scope-check flake — "check incr user_access_token scope fail".
+  // Field report 2026-06-07: a mode-F table fill saw 15 identical
+  // updateDocBlock calls succeed, then 2200 — same UAT, so the scope was
+  // granted; Feishu's incremental-scope check is intermittently flaky under
+  // rapid-fire docx writes. A short-backoff retry usually clears it.
+  2200: { action: 'retry', reason: 'docx_scope_check_transient' },
+
   // Rate limited — Feishu throttles, try once more after a brief pause.
   42101:  { action: 'retry', reason: 'bot_rate_limited' },
   // Frequency control variants occasionally observed.

package/src/test-all.js

@@ -326,6 +326,18 @@ main().catch(console.error).finally(() => {
     console.error('doc-table: FAIL', e);
     process.exitCode = 1;
   });
+  require('./test-doc-blocks-pagination').run().catch(e => {
+    console.error('doc-blocks-pagination: FAIL', e);
+    process.exitCode = 1;
+  });
+  require('./test-pagination-cursor-chain').run().catch(e => {
+    console.error('pagination-cursor-chain: FAIL', e);
+    process.exitCode = 1;
+  });
+  require('./test-doc-block-media').run().catch(e => {
+    console.error('doc-block-media: FAIL', e);
+    process.exitCode = 1;
+  });
   require('./test-switch-profile').run().catch(e => {
     console.error('switch-profile-e2e: FAIL', e);
     process.exitCode = 1;
@@ -377,6 +389,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