feishu-user-plugin 1.3.15 → 1.3.17

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.15",
+  "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.15",
+  "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.15",
+  "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,57 @@ 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。
+
+### Added
+
+- **list_files 看得见你的个人空间了（用户报障修复）**：此前 `list_files` 走纯 app token，bot 对个人空间（"我的空间"）文件夹 403，导致 `upload_drive_file` 走 UAT 传上去的文件**不可发现、也不可删除**（`manage_drive_file(action=delete)` 需要的 file_token 拿不到）。现在 UAT 优先、bot fallback：配置 UAT 后空 `folder_token` 列你自己的"我的空间"根目录。新增 `page_size` / `page_token` 入参与 `nextPageToken` 返回；root 空结果且走 bot 路径时附 `scopeHint` 解释 bot root ≠ 我的空间。（`src/clients/official/drive.js`）
+- **search_docs / search_wiki 分页游标**：新增 `page_size` / `offset` 入参，`hasMore` 时返回 `nextOffset` 直接回填即可翻页；此前只有 `hasMore` 没有可用游标，截断的尾部恰好可能藏着要找的个人空间文档。异常的 `has_more:true` 空页不发 cursor，防止翻页死循环。坏参数（NaN / 负数）收敛为非负整数后才发给飞书。
+
+### Changed
+
+- **search_docs / search_wiki / get_wiki_node 改 UAT-first**：suite 搜索 API 只索引调用身份可见的内容，app 身份搜不到个人空间文档（报障里上传的 PDF 就是这样消失的）。三条路径与 `list_files` 一并走 `_asUserOrApp`（UAT 优先、bot fallback，被迫走 bot 时返回 ⚠ fallbackWarning），响应统一带 `viaUser` 标明视角归属。`get_wiki_node` 保持裸 node 返回形状（resolver 兼容），additive 附加 `viaUser` / `fallbackWarning`；obj_token 合成正则不受新错误形状影响（953001 与 live 实测 131005 双分支测试钉死）。
+- **依赖升级**：protobufjs 7.5.6 → 8.6.0（cookie protobuf 发送层经真实发送探针 + 读回验证）；`@larksuiteoapi/node-sdk` 1.63.1 → 1.66.0（official API 读路径实测）。
+- **MCP Registry namespace** 指向 `io.github.zhuzhen-team`（仓库迁移收尾）。
+
+### Test scenarios
+
+- 配置 UAT 后调 `list_files`（空参）应列出你"我的空间"根目录且 `viaUser:true`
+- `upload_drive_file` 上传 → `list_files` 拿 file_token → `manage_drive_file(action=delete)` 删除 → 再 `list_files` 确认消失
+- `search_docs` 搜个人空间上传的 PDF 标题应能命中，`page_size`+`offset` 翻页两页无重叠
+
 ## [1.3.15] - 2026-05-31
 
 两条增强：文档建表格不再让 agent 猜 block_type；UAT 频繁重新授权的根因（良性 refresh_token 轮换竞态被误判为撤销）修掉。无 schema 变化、无新工具（仍 85）、无 breaking API。升级后重启 Claude Code / Codex 自动拉 v1.3.15。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "mcpName": "io.github.EthanQC/feishu-user-plugin",
-  "version": "1.3.15",
+  "mcpName": "io.github.zhuzhen-team/feishu-user-plugin",
+  "version": "1.3.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": {
@@ -64,7 +64,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^16.4.7",
     "feishu-docx": "^0.7.0",
-    "protobufjs": "^7.5.6"
+    "protobufjs": "^8.6.0"
   },
   "devDependencies": {
     "husky": "^9.1.7"

package/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.15"
-description: "All-in-one Feishu MCP server + CLI tool — send messages as yourself (incl. batch_send), read group/P2P chats (auto-expands merge_forward), manage docs/tables/wiki (full CRUD)/drive, OKR (with progress writes), calendar (read+write), Tasks v2, multi-profile auto-switch, real-time WS events. v1.3.15: manage_doc_block gains a table create mode — agents stop guessing the table block_type (tables are 31, not 40); the plugin builds the block_type=31 table, fills each cell by updating its auto-created text block (no stray empty blocks), resolves cells scoped (no whole-doc 500-block cap) and fails loud rather than silently dropping content. UAT refresh now self-heals a benign refresh_token rotation race: on invalid_grant it re-reads disk and adopts a peer's freshly-persisted valid token (snapshotting the sent token pre-await for the in-process hot-reload case) instead of false-flipping to UAT_REVOKED and pushing the user through a needless oauth re-consent."
+version: "1.3.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/drive.md

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

package/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) {