feishu-user-plugin 1.3.16 → 1.3.17

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.16",
+  "version": "1.3.17",
   "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.16",
+  "version": "1.3.17",
   "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.16",
+  "version": "1.3.17",
   "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,36 @@ 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.17] - 2026-06-08
+
+本版围绕读路径完整性做一轮系统性收口：大文档与大列表不再静默截断、批量写的部分失败不再被读作全成功、文档表格 / 媒体块建失败可定位可修复。85 工具数不变，`get_doc_blocks` / `manage_doc_block` / `read_messages` / `read_p2p_messages` / `list_wiki_nodes` / `manage_bitable_record` 等 schema 新增分页或上报字段，无 breaking API。升级后重启 Claude Code / Codex 自动拉 v1.3.17。
+
+### Added
+
+- **get_doc_blocks / read_doc_markdown 分页拉全量**：跟进 `page_token` 拉完整块树，`hasMore:false` 才代表拉全；此前单页静默截断在 500 块，大文档（一次报障是 280+ 块 / ~300KB）尾部"消失"且无任何标志，调用方误以为那部分块没建成功。`get_doc_blocks` 新增 `max_blocks` 限定单次返回 + `nextPageToken` 续拉，被限定的返回带 `truncated:true`；`read_doc_markdown` 块树不完整时末尾追加 `[output truncated]` 注记。（src/clients/official/docs.js）
+- **read_messages / read_p2p_messages / list_wiki_nodes / manage_bitable_record(search) 分页续拉**：四条读路径新增 `page_token` 入参，`hasMore:true` 时把返回的 `pageToken` 回填即可翻页；此前 client 已返回游标但工具层丢弃 / schema 无入参，超出单页窗口（消息默认 20 上限 50、wiki 节点 50、bitable 默认 20）的内容拿不到也续不了，digest / 全表扫描类任务据此得出残缺结论。
+- **manage_members(add) 部分失败上报**：新增 `notExistedIds`（用户不存在）/ `pendingApprovalIds`（卡入群审批、尚未进群），任一非空时响应顶部 ⚠ 逐一点名；此前只透 `invalidIds`，后两类被静默吞掉，半失败读作全员入群（卡审批的"成员"后续 @ 不到）。字段名对照飞书 OpenAPI 生成的 SDK 类型核验。（src/clients/official/groups.js）
+
+### Fixed
+
+- **manage_doc_block 建表填格部分失败可恢复**：mode F 填格遇瞬态错误（`code=2200` scope-check 抖动 / 限频 / 5xx）自动退避重试；重试后仍失败的格子记录 `failedCells:[{row,col,cellId,textBlockId,reason,skipped}]`（row/col 0 起算）随成功结果返回、不再整体抛错，连续 3 格失败止损并标 `skipped`。逐格 `action=update`（block_id 传 textBlockId）补内容即可，不必重建表。一次报障是 7×3 表第 6 行起填格失败、整表残缺且拿不到已填清单。（src/clients/official/docs.js）
+- **list_wiki_spaces 拉全量**：内部跟进 `page_token` 拉完整空间列表；此前单页截断在 50，第 51+ 个空间的 `space_id` 无法发现，后续 `list_wiki_nodes` / `create_wiki_node` 选不到 parent。（src/clients/official/wiki.js）
+- **图片 / 文件块三步建块瞬态重试 + 孤儿可定位**：`createDocBlockWithImage` / `createDocBlockWithFile`（建占位块 → 上传 → PATCH）的上传与 PATCH 步骤自动重试瞬态错误；持续失败时错误携带占位块 `blockId`（上传已成功时附媒体 token + 含 `document_id` 的修复指引），不必全文找空块。（src/clients/official/docs.js）
+- **空页不再当分页终止信号**：飞书因权限过滤可能返回空页 + `has_more:true` 但后面还有数据（其 `spaceNode.list` API 文档明确写"可以继续分页请求"）；`getDocBlocks` / `listWikiSpaces` 内部循环不再在空页停（停滞保护改由 token 守卫 + 页数 backstop），空页 + 前进游标继续翻。`list_wiki_nodes` schema 同步提醒 agent 空页 + hasMore 要续翻。（src/clients/official/docs.js、wiki.js）
+- **error-codes：2200 归类 retry**：docx 的 "check incr user_access_token scope fail" 是 scope-check 服务的瞬态抖动（同一 UAT 前序调用均成功、scope 本已授权），归为可重试。（src/error-codes.js）
+- **server.json 目录描述词边界截断**：registry catalog 描述改为词边界截断 + 省略号，不再切在半个词（32 个长描述受益）；运行时 MCP client 经 `tools/list` 拿的仍是完整描述。（scripts/sync-server-json.js）
+
+### Changed
+
+- **update_text_elements 整段替换语义强调**：`manage_doc_block(action=update)` 的 `update_text_elements` 全量覆盖该块的 elements（**非** patch / append），漏传的 element（加粗前缀、链接等）永久丢失；改局部应先 `get_doc_blocks` 读原块、整组传回。schema 描述 + docs/TOOLS.md + CLAUDE.md + skill reference 四处加粗。
+
+### Test scenarios
+
+- 280+ 块大文档调 `get_doc_blocks` 应返回全部块、`hasMore:false`；`read_doc_markdown` 渲染到末段不截断
+- `read_messages` 对消息密集的群 `hasMore:true` 时回填 `page_token` 应拿到更早的消息
+- `manage_doc_block(action=create, table=7×3)` 21 格应全部填充；瞬态失败时返回 `failedCells` 而非整体报错
+- `list_wiki_spaces` 在加入 >50 个空间的账号应返回全部、`hasMore:false`
+
 ## [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。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
   "mcpName": "io.github.zhuzhen-team/feishu-user-plugin",
-  "version": "1.3.16",
+  "version": "1.3.17",
   "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": {

package/scripts/probe-feishu-docx.js

@@ -91,9 +91,8 @@ const BLOCK_LABELS = {
   if (process.env.LARK_USER_ACCESS_TOKEN) c.loadUAT();
 
   // --- Fetch blocks ---
-  // NOTE: getDocBlocks fetches up to 500 blocks (no pagination). Docs longer
-  // than that produce a truncated fixture / undercount. Out of scope for this
-  // one-shot probe.
+  // getDocBlocks follows page_token pagination to completion (v1.3.17), so
+  // the fixture covers the whole document regardless of size.
   let blocks;
   try {
     const result = await c.getDocBlocks(rawDocId);

package/scripts/sync-server-json.js

@@ -17,10 +17,23 @@ const SERVER_JSON = path.join(ROOT, 'server.json');
 const PKG = require(path.join(ROOT, 'package.json'));
 const { TOOLS } = require(path.join(ROOT, 'src', 'server'));
 
+// Truncate a description to at most `limit` chars for the registry catalog.
+// Cuts at the last word boundary (when one exists in the tail) and appends an
+// ellipsis, so server.json never ends a description mid-word — the full text
+// still reaches MCP clients at runtime via tools/list (this is catalog
+// metadata only). PR #121 review.
+function truncateForCatalog(s, limit = 200) {
+  if (s.length <= limit) return s;
+  const slice = s.slice(0, limit - 1); // leave room for the ellipsis
+  const lastSpace = slice.lastIndexOf(' ');
+  const cut = lastSpace > limit * 0.6 ? slice.slice(0, lastSpace) : slice;
+  return cut.replace(/[\s,;.:—-]+$/, '') + '…';
+}
+
 function deriveToolEntry(t) {
   // Strip the "[Plugin]"/"[Cookie]"/etc category prefix from descriptions for compactness.
   const desc = (t.description || '').replace(/^\[[^\]]+\]\s*/, '');
-  return { name: t.name, description: desc.split('\n')[0].slice(0, 200) };
+  return { name: t.name, description: truncateForCatalog(desc.split('\n')[0], 200) };
 }
 
 const existing = JSON.parse(fs.readFileSync(SERVER_JSON, 'utf8'));

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

@@ -1,7 +1,7 @@
 ---
 name: feishu-user-plugin
-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."
+version: "1.3.17"
+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.17: read-path completeness — get_doc_blocks / read_doc_markdown now paginate past the old silent 500-block cap (hasMore / truncated / page_token / max_blocks); read_messages / read_p2p_messages / list_wiki_nodes / manage_bitable_record(search) gain page_token cursors and list_wiki_spaces fetches all spaces (was capped at 50); empty pages with has_more no longer stop pagination early. manage_doc_block table fills retry transient errors (code=2200) and report failedCells instead of aborting; manage_members(add) surfaces not-existed / pending-approval ids; image/file block creation retries and names orphaned placeholders on failure. update_text_elements full-replace semantics emphasized. 85 tools + 9 prompts unchanged."
 allowed-tools: send_to_user, send_to_group, send_as_user, send_image_as_user, send_file_as_user, send_post_as_user, batch_send, send_card_as_user, search_contacts, create_p2p_chat, get_chat_info, get_user_info, get_login_status, list_profiles, switch_profile, manage_profile_hints, read_p2p_messages, list_user_chats, list_chats, read_messages, search_messages, send_message_as_bot, reply_message, forward_message, delete_message, update_message, add_reaction, delete_reaction, pin_message, create_group, update_group, list_members, manage_members, search_docs, read_doc, get_doc_blocks, create_doc, manage_doc_block, read_doc_markdown, manage_bitable_app, manage_bitable_table, manage_bitable_field, manage_bitable_view, manage_bitable_record, upload_bitable_attachment, list_wiki_spaces, search_wiki, list_wiki_nodes, get_wiki_node, create_wiki_node, update_wiki_node, move_wiki_node, copy_wiki_node, delete_wiki_node, list_files, create_folder, upload_drive_file, manage_drive_file, upload_image, upload_file, download_message_resource, download_doc_image, list_user_okrs, get_okrs, list_okr_periods, create_okr_progress_record, list_okr_progress_records, delete_okr_progress_record, list_calendars, list_calendar_events, get_calendar_event, create_calendar_event, update_calendar_event, delete_calendar_event, respond_calendar_event, get_freebusy, list_tasks, get_task, create_task, update_task, complete_task, delete_task, manage_task_members, get_new_events, manage_ws_status
 user_invocable: true
 ---

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

@@ -23,6 +23,7 @@
    - `table` 形如 `{"rows":2,"columns":2,"cells":[["姓名","角色"],["Ann","PM"]]}`：`cells` 行优先，可省略或留空字符串表示空格
    - 插件内部建 `block_type=31` 表格、由飞书自动生成单元格（`block_type=32`）、逐格填内容——**不要自己用 `children` 拼 table block 或猜 block_type**（表格是 31 不是 40，猜错会报 `invalid_param`）
 2. 返回 `tableBlockId` + 行优先的 `cells` 单元格 ID 网格
+3. 若个别单元格填充失败（瞬态错误已自动重试），返回里会带 `failedCells:[{row,col,cellId,textBlockId?,reason}]`（row/col 0 起算）——逐格用 `manage_doc_block(action=update, block_id=<textBlockId>)` 补内容即可，**不必删表重建**
 
 ### 写决策树等纯文本结构
 表格只用于真正的二维数据；决策树、流程、缩进结构用 `children` 里的文本块（`block_type=2`）+ 代码块（`block_type=14`）表达即可，不依赖表格线。
@@ -37,3 +38,5 @@
 - 文档操作使用 Official API（需要 LARK_APP_ID）
 - 搜索结果受机器人权限范围限制
 - 建表格走 `manage_doc_block` 的 `table` 模式，不要手拼 block——表格 `block_type=31`、单元格 `32`
+- `manage_doc_block(action=update)` 的 `update_text_elements` 是**整段替换**（非 patch / append）：漏传的 element（加粗前缀、链接等）会永久丢失，改局部先 `get_doc_blocks` 读出原 elements、改完整组传回
+- 读大文档：`get_doc_blocks` / `read_doc_markdown` 自动分页拉全量，`hasMore:false` 才代表拿到了完整块树

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

@@ -13,7 +13,7 @@
 2. 找到节点后可用 `read_doc` 读取其文档内容
 
 ### 浏览节点
-1. 用 `list_wiki_nodes` 列出指定空间的节点树
+1. 用 `list_wiki_nodes` 列出指定空间的节点树（每页 50 个；`hasMore:true` 时把返回的 `pageToken` 传回 `page_token` 翻页）
 2. 可传 `parent_node_token` 浏览子节点
 
 ## 示例

package/src/clients/official/bitable.js

@@ -116,7 +116,12 @@ module.exports = {
       }),
       label: 'searchRecords',
     });
-    return { items: res.data.items || [], total: res.data.total, hasMore: res.data.has_more };
+    // pageToken accompanies hasMore (2026-06-07 audit) — hasMore + total
+    // without the resume cursor stranded callers at the first page of a
+    // potentially thousands-row table.
+    const out = { items: res.data.items || [], total: res.data.total, hasMore: res.data.has_more };
+    if (res.data.page_token) out.pageToken = res.data.page_token;
+    return out;
   },
 
   async createBitableRecord(appToken, tableId, fields) {

package/src/clients/official/docs.js

@@ -6,6 +6,43 @@
 // 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 ---
@@ -70,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
@@ -123,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');
@@ -166,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) {
@@ -224,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');
     }
@@ -248,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 };
   },
@@ -296,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');
     }
@@ -332,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 };
   },
@@ -377,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/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,18 +11,51 @@ 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;
@@ -104,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) ---