feishu-user-plugin 1.3.14 → 1.3.15

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.14",
+  "version": "1.3.15",
   "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.14",
+  "version": "1.3.15",
   "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.14",
+  "version": "1.3.15",
   "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,23 @@ 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.15] - 2026-05-31
+
+两条增强：文档建表格不再让 agent 猜 block_type；UAT 频繁重新授权的根因（良性 refresh_token 轮换竞态被误判为撤销）修掉。无 schema 变化、无新工具（仍 85）、无 breaking API。升级后重启 Claude Code / Codex 自动拉 v1.3.15。
+
+### Added
+
+- **manage_doc_block 新增 table 创建模式（mode F）**：`manage_doc_block(action=create, table={rows, columns, cells?, column_width?, header_row?, header_column?})` 一步建表 + 填格。此前 agent 要自己拼 table block 并猜 `block_type`（猜成 40 → 飞书报 `invalid_param`）；现在插件内部建 `block_type=31` 表、由飞书自动生成 `block_type=32` 单元格、逐格 UPDATE 单元格自带的空文本块（无遗留空块）。单元格 ID 行优先解析自创建响应，回退到 scoped `getBlockChildren`（不吃整文档 500 块上限），解析不全则报错而非静默丢内容。返回 `tableBlockId` + 行优先 `cells` 网格。`skills/feishu-user-plugin/references/doc.md` 同步补建表 + 决策树指引。
+
+### Fixed
+
+- **UAT refresh `invalid_grant` 良性轮换竞态自愈**：频繁收到飞书"授权操作通知"、"没撑过一晚上"的根因。飞书 refresh_token 每次刷新滚动轮换；当跨进程互斥失效时（20s 锁超时兜底，或 v1.3.14 升级期间新旧锁路径 `~/.claude/feishu-uat-refresh.lock` vs `~/.feishu-user-plugin/uat-refresh.lock` 不对齐），并发刷新的输家拿 `invalid_grant`，此前 `refreshUAT` 直接判 `UAT_REVOKED` 并提示重跑 oauth——而赢家此刻早已把有效新 token 落盘。现在 `invalid_grant` 时先快照已发送的 refresh_token、回查磁盘，若已有"不同且仍有效"的 token（peer 赢了轮换）就采用并恢复，只有磁盘也是同一个死 token 才真判撤销；按 client 状态判定（而非 `adoptPersistedUATIfNewer` 返回值）兼顾 in-process / credentials-monitor hot-reload race。（`src/auth/uat.js`）
+
+### Test scenarios
+
+- 多进程 / 多版本并发刷 UAT 时，良性轮换不再弹"授权操作通知"、不再提示重跑 oauth（`auth_time` 不跳）
+- `manage_doc_block(action=create, table={rows:2,columns:2,cells:[["A","B"],["C","D"]]})` 在文档里生成 2×2 表、四格有内容、无空行
+
 ## [1.3.14] - 2026-05-21
 
 **TL;DR**：纯收紧的 bug fix / security release。无 schema 变化、无新工具、无 breaking API。升级后重启 Claude Code / Codex 自动拉 v1.3.14；如果之前还没跑过 `migrate --confirm`，**强烈建议**跑一次（canonical store 是 v1.3.7+ 推荐路径，v1.3.14 把 UAT refresh 锁也搬过来完成最后一块）。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
   "mcpName": "io.github.EthanQC/feishu-user-plugin",
-  "version": "1.3.14",
+  "version": "1.3.15",
   "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/skills/feishu-user-plugin/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: feishu-user-plugin
-version: "1.3.14"
-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.14: UAT refresh-lock moved to canonical home (Codex-only users now get cross-process mutex), invalid_grant flips identity to UAT_REVOKED with clear oauth re-run guidance, refresh-error redaction (no raw response body in Error.message), three-stage adoptPersistedUATIfNewer race-shield, cookie heartbeat ws-owner-gated (no more N-times API spam from 30+ concurrent sessions), OAuth/setup all fetch calls timeout-bounded, oauth-auto.js dead code with token leak removed, OAuth browser callback no longer displays token bytes, decodeTokenExpiry malformed-JWT warning deduped, Lark Desktop reactor cold-start debounce fixed, 27 new fixture-based tests (test-uat-lifecycle + test-cookie-heartbeat) plus the cross-process race test repaired, TROUBLESHOOTING.md grew 4 sections (frequent consent notification / UAT-not-refreshing / mixed-version upgrade window / migrate-then-stale-env)."
+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."
 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

@@ -17,11 +17,23 @@
 1. 用 `create_doc` 创建新文档（传入标题和可选 folder_id）
 2. 返回文档 ID
 
+### 在文档里建表格
+1. 用 `manage_doc_block(action=create, document_id, parent_block_id, table={...})` 建表
+   - `parent_block_id` 用 `document_id` 表示文档根（或某个块 ID 表示插在该块下）
+   - `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 网格
+
+### 写决策树等纯文本结构
+表格只用于真正的二维数据；决策树、流程、缩进结构用 `children` 里的文本块（`block_type=2`）+ 代码块（`block_type=14`）表达即可，不依赖表格线。
+
 ## 示例
 - `/doc search MCP 协议`
 - `/doc read doxcnXXXXXX`
 - `/doc create 本周工作总结`
+- `/doc 在 doxcnXXXX 里建一个 2×2 表格，表头 姓名/角色`
 
 ## 注意
 - 文档操作使用 Official API（需要 LARK_APP_ID）
 - 搜索结果受机器人权限范围限制
+- 建表格走 `manage_doc_block` 的 `table` 模式，不要手拼 block——表格 `block_type=31`、单元格 `32`

package/src/auth/uat.js

@@ -163,6 +163,12 @@ async function refreshUAT(client) {
       return client._uat;
     }
     if (!client._uatRefresh) throw new Error('UAT expired and no refresh token. Run: npx feishu-user-plugin oauth');
+    // Snapshot the refresh_token we are about to send BEFORE awaiting. A peer
+    // in-process refresh or the credentials monitor can hot-reload
+    // client._uatRefresh during the round-trip; the invalid_grant self-heal
+    // below must compare against the token actually sent, not a field that may
+    // have already rotated. (Codex review, PR #111.)
+    const attemptedRefresh = client._uatRefresh;
     const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
@@ -170,7 +176,7 @@ async function refreshUAT(client) {
         grant_type: 'refresh_token',
         client_id: client.appId,
         client_secret: client.appSecret,
-        refresh_token: client._uatRefresh,
+        refresh_token: attemptedRefresh,
       }),
     });
     const data = await res.json();
@@ -187,6 +193,37 @@ async function refreshUAT(client) {
       // UAT_REVOKED, and withIdentityFallback can give the LLM clear guidance.
       const isInvalidGrant = errCode === 'invalid_grant' || errCode === 20064;
       if (isInvalidGrant) {
+        // v1.3.15 — self-heal a benign refresh_token rotation race before
+        // declaring the 7-day chain dead. When cross-process mutual exclusion
+        // is defeated (lock-acquire timeout fallthrough above, or a transient
+        // mixed-version upgrade window where old/new instances use different
+        // lock paths), two processes can refresh with the same refresh_token;
+        // Feishu rotates it for the winner and rejects the loser with
+        // invalid_grant. By the time the loser lands here, the winner has very
+        // likely already persisted a fresh, valid, DIFFERENT token to disk.
+        // Re-read disk: if it now holds a different, still-valid token, our
+        // invalid_grant just means "our copy was rotated away" — adopt it and
+        // recover, instead of flipping to UAT_REVOKED and pushing the user
+        // through a needless `oauth` re-consent (the "授权操作通知 没撑过一晚上"
+        // symptom). Only when disk still holds the SAME (now-dead) refresh_token
+        // is this a genuine revocation. Covered by test-uat-lifecycle
+        // "invalid_grant + peer rotated fresh token to disk".
+        now = Math.floor(Date.now() / 1000);
+        // Best-effort re-sync from disk (a no-op if a peer/monitor already
+        // updated this client in memory). Then recover iff we now hold a
+        // DIFFERENT, still-valid token than the one we actually sent — this
+        // covers both the cross-process race (disk holds the winner) and the
+        // in-process / hot-reload race (client already holds the winner).
+        // Gating on the resulting client state, rather than on
+        // adoptPersistedUATIfNewer()'s return value, is what lets the
+        // hot-reload case recover (adopt is a no-op there). (Codex review, PR #111.)
+        adoptPersistedUATIfNewer(client);
+        if (client._uat
+            && client._uatRefresh !== attemptedRefresh
+            && client._uatExpires > now + 300) {
+          console.error('[feishu-user-plugin] UAT invalid_grant on the sent refresh_token; a different valid token is present (peer won the rotation) — adopted, no re-consent needed');
+          return client._uat;
+        }
         try {
           const { _refineIdentity, IdentityState } = require('./identity-state');
           _refineIdentity(client, IdentityState.UAT_REVOKED);

package/src/clients/official/docs.js

@@ -63,6 +63,22 @@ module.exports = {
     return { items: res.data.items || [] };
   },
 
+  // Direct children of a single block — scoped, so it does not inherit the
+  // whole-document 500-block cap of getDocBlocks. Used by createDocTable to map
+  // a table's cells (and each cell's text block) reliably in large documents.
+  async getBlockChildren(documentId, blockId) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}/children`,
+      query: { page_size: '500' },
+      sdkFn: () => this.client.docx.documentBlockChildren.get({
+        path: { document_id: documentId, block_id: blockId },
+        params: { page_size: 500 },
+      }),
+      label: 'getBlockChildren',
+    });
+    return { items: res.data.items || [] };
+  },
+
   async createDocBlock(documentId, parentBlockId, children, index) {
     const data = { children };
     if (index !== undefined) data.index = index;
@@ -79,6 +95,85 @@ module.exports = {
     return { blocks: res.data.children || [], fallbackWarning: res._fallbackWarning || null };
   },
 
+  // Create a Feishu docx table (block_type=31) and optionally fill its cells —
+  // so callers never have to know docx block types. Added after field reports
+  // of agents guessing the table block_type (40 is wrong; 31 table / 32 cell).
+  // Flow:
+  //   1) create the table block with row_size/column_size — Feishu auto-creates
+  //      the table_cell (32) children (row-major) and gives each cell an empty
+  //      text block.
+  //   2) read the table back to map cell_id -> its auto-created text block.
+  //   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 } = {}) {
+    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');
+    }
+    const property = { row_size: rows, column_size: columns };
+    if (Array.isArray(columnWidth) && columnWidth.length === columns) property.column_width = columnWidth;
+    if (headerRow) property.header_row = true;
+    if (headerColumn) property.header_column = true;
+    const createBody = { children: [{ block_type: 31, table: { property } }] };
+    if (index !== undefined) createBody.index = index;
+    const created = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${parentBlockId}/children`,
+      method: 'POST',
+      body: createBody,
+      sdkFn: () => this.client.docx.documentBlockChildren.create({
+        path: { document_id: documentId, block_id: parentBlockId },
+        data: createBody,
+      }),
+      label: 'createDocTable',
+    });
+    const tableCreated = (created.data.children || [])[0];
+    const tableBlockId = tableCreated?.block_id;
+    if (!tableBlockId) throw new Error(`createDocTable: no table block_id returned: ${JSON.stringify(created.data).slice(0, 400)}`);
+    const viaUser = !!created._viaUser;
+    const fallbackWarning = created._fallbackWarning || null;
+
+    // Resolve the cell IDs. Prefer the create response; else fetch the table
+    // block's children directly (scoped — NOT the whole-doc getDocBlocks, which
+    // caps at 500 blocks and would silently lose an appended table's cells in a
+    // large document). Fail loud rather than silently dropping requested content.
+    let flatCellIds = tableCreated.table?.cells || tableCreated.children || [];
+    if (flatCellIds.length < rows * columns) {
+      flatCellIds = ((await this.getBlockChildren(documentId, tableBlockId)).items || []).map(b => b.block_id);
+    }
+    if (flatCellIds.length < rows * columns) {
+      throw new Error(`createDocTable: created table ${tableBlockId} but resolved only ${flatCellIds.length}/${rows * columns} cells — aborting fill to avoid silently dropping content.`);
+    }
+    const grid = [];
+    for (let r = 0; r < rows; r++) grid.push(flatCellIds.slice(r * columns, (r + 1) * columns));
+
+    let filled = 0;
+    if (Array.isArray(cells)) {
+      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}`);
+          // 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 }]);
+          }
+          filled++;
+        }
+      }
+    }
+    return { tableBlockId, cells: grid, rows, columns, filled, viaUser, fallbackWarning };
+  },
+
   async updateDocBlock(documentId, blockId, updateBody) {
     const res = await this._asUserOrApp({
       uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}`,

package/src/test-all.js

@@ -322,6 +322,10 @@ async function main() {
 main().catch(console.error).finally(() => {
   // Fixture-based unit test — runs regardless of credential availability
   require('./test-read-doc-markdown').run();
+  require('./test-doc-table').run().catch(e => {
+    console.error('doc-table: FAIL', e);
+    process.exitCode = 1;
+  });
   require('./test-switch-profile').run().catch(e => {
     console.error('switch-profile-e2e: FAIL', e);
     process.exitCode = 1;

package/src/test-doc-table.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// Unit tests for createDocTable (manage_doc_block create mode F — tables).
+//
+// Guards the payload contract (block_type=31 table, row_size/column_size), the
+// cell-fill behaviour (UPDATE an existing auto-created text block — no stray
+// empty blocks — else CREATE one), and the fail-loud behaviour when the table's
+// cells cannot be resolved (so large docs never silently drop content). Pure
+// unit: the client methods (_asUserOrApp / getBlockChildren / updateDocBlock /
+// createDocBlock) are stubbed, so no network. End-to-end behaviour is verified
+// separately against live Feishu (create doc → table → read back → delete).
+'use strict';
+
+const assert = require('assert');
+const docs = require('./clients/official/docs');
+
+let pass = 0, fail = 0;
+async function ok(name, fn) {
+  try { await fn(); console.log(`  OK  ${name}`); pass++; }
+  catch (e) { console.log(`  FAIL ${name}: ${e.message}`); fail++; }
+}
+
+// Build a stubbed `this` for createDocTable.
+//   cellIds          — the table's cells (row-major)
+//   cellsInCreate    — true: create response carries cell ids; false: forces a
+//                      scoped getBlockChildren(table) lookup
+//   cellHasText      — true: each cell already has an auto text block (UPDATE);
+//                      false: empty cell (CREATE)
+//   resolvableCells  — cell ids that getBlockChildren(table) will return (defaults
+//                      to cellIds); set shorter to exercise fail-loud
+function stub({ cellIds, cellsInCreate = true, cellHasText = true, resolvableCells } = {}) {
+  const calls = { createBody: null, updates: [], creates: [], childFetches: [] };
+  const self = {
+    async _asUserOrApp({ body }) {
+      calls.createBody = body;
+      const tbl = { block_id: 'tbl1' };
+      if (cellsInCreate) tbl.children = cellIds;
+      return { data: { children: [tbl] }, _viaUser: true, _fallbackWarning: null };
+    },
+    async getBlockChildren(documentId, blockId) {
+      calls.childFetches.push(blockId);
+      if (blockId === 'tbl1') {
+        const ids = resolvableCells || cellIds;
+        return { items: ids.map(id => ({ block_id: id, block_type: 32 })) };
+      }
+      // a cell → its auto text block (or none)
+      return { items: cellHasText ? [{ block_id: 't-' + blockId, block_type: 2 }] : [] };
+    },
+    async updateDocBlock(documentId, blockId, body) { calls.updates.push({ blockId, body }); return { block: {} }; },
+    async createDocBlock(documentId, parent, children) { calls.creates.push({ parent, children }); return { blocks: [] }; },
+  };
+  return { self, calls };
+}
+
+async function run() {
+  console.log('=== test-doc-table ===');
+
+  await ok('builds block_type=31 payload + fills by UPDATEing each cell\'s existing text (no stray blocks)', async () => {
+    const { self, calls } = stub({ cellIds: ['c00', 'c01', 'c10', 'c11'], cellsInCreate: true, cellHasText: true });
+    const r = await docs.createDocTable.call(self, 'docX', 'docX', { rows: 2, columns: 2, cells: [['A', 'B'], ['C', 'D']] });
+    const tableBody = calls.createBody.children[0];
+    assert.strictEqual(tableBody.block_type, 31, 'table block_type must be 31 (not 40)');
+    assert.strictEqual(tableBody.table.property.row_size, 2);
+    assert.strictEqual(tableBody.table.property.column_size, 2);
+    assert.deepStrictEqual(r.cells, [['c00', 'c01'], ['c10', 'c11']], 'cells mapped row-major');
+    assert.strictEqual(r.filled, 4);
+    assert.strictEqual(calls.updates.length, 4, 'should UPDATE 4 existing cell text blocks');
+    assert.strictEqual(calls.creates.length, 0, 'should NOT create extra blocks when the cell already has a text block');
+    assert.strictEqual(calls.updates[0].body.update_text_elements.elements[0].text_run.content, 'A');
+    assert.strictEqual(r.viaUser, true);
+  });
+
+  await ok('CREATEs a text block when a cell has no auto text block', async () => {
+    const { self, calls } = stub({ cellIds: ['c0', 'c1'], cellsInCreate: true, cellHasText: false });
+    const r = await docs.createDocTable.call(self, 'd', 'd', { rows: 1, columns: 2, cells: [['X', 'Y']] });
+    assert.strictEqual(r.filled, 2);
+    assert.strictEqual(calls.creates.length, 2, 'should CREATE a text block in each empty cell');
+    assert.strictEqual(calls.updates.length, 0);
+    assert.strictEqual(calls.creates[0].children[0].block_type, 2, 'created child is a text block');
+  });
+
+  await ok('resolves cells via scoped getBlockChildren when the create response lacks them', async () => {
+    const { self, calls } = stub({ cellIds: ['c0', 'c1'], cellsInCreate: false, cellHasText: true });
+    const r = await docs.createDocTable.call(self, 'd', 'd', { rows: 1, columns: 2, cells: [['X', 'Y']] });
+    assert.deepStrictEqual(r.cells, [['c0', 'c1']]);
+    assert.strictEqual(r.filled, 2);
+    assert.ok(calls.childFetches.includes('tbl1'), 'should scope-fetch the table block children when create response lacks cells');
+  });
+
+  await ok('fails loud (throws) when cells cannot be fully resolved — never silently drops content', async () => {
+    // create response lacks cells AND scoped lookup returns too few (e.g. >500-block doc)
+    const { self } = stub({ cellIds: ['c0', 'c1'], cellsInCreate: false, resolvableCells: ['c0'] });
+    let threw = false, msg = '';
+    try { await docs.createDocTable.call(self, 'd', 'd', { rows: 1, columns: 2, cells: [['X', 'Y']] }); }
+    catch (e) { threw = true; msg = e.message; }
+    assert.ok(threw, 'should throw rather than return a low-filled success');
+    assert.ok(/resolved only 1\/2 cells/.test(msg), `error should name the shortfall: ${msg}`);
+  });
+
+  await ok('leaves omitted/blank cells empty and counts only filled', async () => {
+    const { self, calls } = stub({ cellIds: ['c0', 'c1', 'c2', 'c3'], cellsInCreate: true, cellHasText: true });
+    const r = await docs.createDocTable.call(self, 'd', 'd', { rows: 2, columns: 2, cells: [['only', ''], [null, 'here']] });
+    assert.strictEqual(r.filled, 2, 'blank/null cells are skipped');
+    assert.strictEqual(calls.updates.length, 2);
+  });
+
+  await ok('rejects rows/columns < 1', async () => {
+    const { self } = stub({ cellIds: [] });
+    for (const bad of [{ rows: 0, columns: 2 }, { rows: 2, columns: 0 }, { rows: -1, columns: 1 }]) {
+      let threw = false;
+      try { await docs.createDocTable.call(self, 'd', 'd', bad); } catch (_) { threw = true; }
+      assert.ok(threw, `rows/columns ${JSON.stringify(bad)} should throw`);
+    }
+  });
+
+  console.log(`\n=== test-doc-table: ${pass} passed, ${fail} failed ===`);
+  if (fail > 0) process.exit(1);
+}
+
+if (require.main === module) {
+  run().catch((e) => { console.error('test-doc-table harness error:', e); process.exit(1); });
+}
+
+module.exports = { run };

package/src/test-uat-lifecycle.js

@@ -276,6 +276,101 @@ async function run() {
     }
   });
 
+  // --- refreshUAT: benign rotation race must self-heal, not false-revoke ---
+  //
+  // A peer process wins the refresh_token rotation and persists a fresh, VALID
+  // token to disk DURING our refresh round-trip; our now-stale refresh_token
+  // then comes back invalid_grant. refreshUAT must adopt the peer's on-disk
+  // token and recover, instead of throwing uatRevoked (which would push the
+  // user through a needless `npx feishu-user-plugin oauth` re-consent — the
+  // root cause of the "授权操作通知 没撑过一晚上" reports).
+  await ok('refreshUAT: invalid_grant + peer rotated fresh token to disk → adopts & recovers (no false revoke)', async () => {
+    os.homedir = () => fakeHome;
+    const now = Math.floor(Date.now() / 1000);
+    // Disk starts equal to our stale in-memory token so the pre-fetch adopt
+    // checks find nothing newer and we proceed into the refresh fetch.
+    writeCanonical({
+      LARK_USER_ACCESS_TOKEN: 'stale.access',
+      LARK_USER_REFRESH_TOKEN: 'stale.refresh',
+      LARK_UAT_EXPIRES: String(now - 3600),
+    });
+
+    const origFetch = global.fetch;
+    global.fetch = async () => {
+      // The winning peer finishes mid-round-trip: persists a fresh VALID token.
+      writeCanonical({
+        LARK_USER_ACCESS_TOKEN: 'winner.access',
+        LARK_USER_REFRESH_TOKEN: 'winner.refresh',
+        LARK_UAT_EXPIRES: String(now + 7200),
+      });
+      // Our stale refresh_token was rotated away on the Feishu side.
+      return { json: async () => ({ error: 'invalid_grant', error_description: 'refresh_token expired' }) };
+    };
+
+    try {
+      const client = {
+        appId: 'test', appSecret: 'test',
+        _uat: 'stale.access',
+        _uatRefresh: 'stale.refresh',
+        _uatExpires: now - 3600,
+      };
+      let thrown = null, ret = null;
+      try { ret = await uat.refreshUAT(client); } catch (e) { thrown = e; }
+      assert.ok(!thrown, `should recover, not throw; got: ${thrown && thrown.message}`);
+      assert.strictEqual(ret, 'winner.access', 'should return the peer-rotated access token');
+      assert.strictEqual(client._uatRefresh, 'winner.refresh', 'should adopt the peer-rotated refresh_token');
+    } finally {
+      global.fetch = origFetch;
+      os.homedir = origHomedir;
+    }
+  });
+
+  // Codex review (PR #111) edge: a peer in-process refresh / credentials-monitor
+  // hot-reloads THIS client in memory (and persists to disk) WHILE our refresh
+  // request — carrying the now-stale token — is still in flight. Because we
+  // snapshot the sent token before awaiting and gate recovery on client state
+  // (not adoptPersistedUATIfNewer's return value), we must still recover instead
+  // of false-revoking. With the pre-fix code (post-await capture) this throws.
+  await ok('refreshUAT: invalid_grant after mid-flight hot-reload to a fresh token → recovers (no false revoke)', async () => {
+    os.homedir = () => fakeHome;
+    const now = Math.floor(Date.now() / 1000);
+    // Disk starts stale so the pre-fetch adopt checks proceed into the fetch.
+    writeCanonical({
+      LARK_USER_ACCESS_TOKEN: 'stale.access',
+      LARK_USER_REFRESH_TOKEN: 'stale.refresh',
+      LARK_UAT_EXPIRES: String(now - 3600),
+    });
+    const client = {
+      appId: 'test', appSecret: 'test',
+      _uat: 'stale.access', _uatRefresh: 'stale.refresh', _uatExpires: now - 3600,
+    };
+
+    const origFetch = global.fetch;
+    global.fetch = async () => {
+      // Concurrent winner finishes mid-flight: persists rotated token to disk
+      // AND a hot-reload updates this very client in memory.
+      writeCanonical({
+        LARK_USER_ACCESS_TOKEN: 'winner.access',
+        LARK_USER_REFRESH_TOKEN: 'winner.refresh',
+        LARK_UAT_EXPIRES: String(now + 7200),
+      });
+      client._uat = 'winner.access';
+      client._uatRefresh = 'winner.refresh';
+      client._uatExpires = now + 7200;
+      return { json: async () => ({ error: 'invalid_grant', error_description: 'refresh_token expired' }) };
+    };
+
+    try {
+      let thrown = null, ret = null;
+      try { ret = await uat.refreshUAT(client); } catch (e) { thrown = e; }
+      assert.ok(!thrown, `should recover, not throw; got: ${thrown && thrown.message}`);
+      assert.strictEqual(ret, 'winner.access', 'should recover the winner token despite mid-flight hot-reload');
+    } finally {
+      global.fetch = origFetch;
+      os.homedir = origHomedir;
+    }
+  });
+
   // identity-state.js redact-regex regression guard. Exercises the actual
   // regex on `_classifyUatFailure` path that the previous "no dead.refresh"
   // assertion in test #14 did NOT cover (the invalid_grant message is

package/src/tools/docs.js

@@ -52,7 +52,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 — five modes:\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  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`).\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: {
@@ -69,6 +69,7 @@ const schemas = [
         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"]]}.' },
       },
       required: ['action', 'document_id'],
     },
@@ -121,8 +122,16 @@ const handlers = {
     switch (args.action) {
       case 'create': {
         need(args.parent_block_id, 'parent_block_id', 'create');
-        const modes = [args.children, args.image_path, args.image_token, args.file_path, args.file_token].filter(Boolean);
-        if (modes.length > 1) return text('manage_doc_block(create): pass exactly ONE of children / image_path / image_token / file_path / file_token.');
+        const modes = [args.children, args.image_path, args.image_token, args.file_path, args.file_token, args.table].filter(Boolean);
+        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, {
+            rows: t.rows, columns: t.columns, cells: t.cells,
+            columnWidth: t.column_width, headerRow: t.header_row, headerColumn: t.header_column,
+            index: args.index,
+          }));
+        }
         if (args.image_path || args.image_token) {
           const r = await official.createDocBlockWithImage(docId, args.parent_block_id, {
             imagePath: args.image_path,
@@ -139,7 +148,7 @@ const handlers = {
           });
           return json(r);
         }
-        if (!args.children) return text('manage_doc_block(create): children, image_path, image_token, file_path, or file_token is required.');
+        if (!args.children) return text('manage_doc_block(create): children, image_path, image_token, file_path, file_token, or table is required.');
         return json(await official.createDocBlock(docId, args.parent_block_id, args.children, args.index));
       }
       case 'update': {