feishu-user-plugin 1.3.13 → 1.3.14

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.13",
+  "version": "1.3.14",
   "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.13",
+  "version": "1.3.14",
   "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.13",
+  "version": "1.3.14",
   "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,80 @@ 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.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 锁也搬过来完成最后一块）。
+
+OAuth / UAT 子系统深度优化：跨进程互斥锁路径迁移到 canonical home、cookie heartbeat 改为 ws-owner 单跑（30+ 并发 session 不再每 4h × N 倍 API call 进飞书 session-keepalive 端点）、refresh 错误处理与 identity 状态机打通（invalid_grant 显式 `err.uatRevoked` → `_classifyUatFailure` 短路成 UAT_REVOKED → `withIdentityFallback` 给 LLM 清晰的"请重跑 oauth"指引）、安全敏感日志清理（含 OAuth 回调浏览器页面 token bytes 不再显示）、Lark Desktop reactor 冷启动 debounce 修复、decodeTokenExpiry 失败 breadcrumb flood-gate、dead code 移除、TROUBLESHOOTING 四段新指引、新增 27 个 fixture-based 测试（test-uat-lifecycle 18 + test-cookie-heartbeat 9）并修复 v1.3.7 起就静默坏掉的跨进程 race 测试。85 工具 9 prompts 不变。
+
+### Security
+
+- **oauth.js: redact `code` field in token-exchange log**（`src/oauth.js:166`）：之前 `console.log` 把 authorization code 明文写 stdout。code 短寿命（~60s）但仍是可换 token 的有效 credential，转写 / 屏幕录制 / 终端 history 会暂存。改为 `code: '***'`。
+- **oauth.js: 浏览器回调页面不再显示 access_token bytes**（`src/oauth.js:251`）：之前 `<p>access_token: ${tokenData.access_token.slice(0, 20)}...</p>` 把 token 前 20 字节贴到 HTML，浏览器 history / 截图 / 屏幕录制都会留痕。改为 `<p>access_token: ✅ 已获取（${len} chars）</p>` —— 长度 attestation 足以证明流程成功，不暴露 token 任何 byte。
+- **删除 `src/oauth-auto.js`**：Playwright dev-only OAuth helper，v1.3.0 起没有 production path 引用、`.npmignore` 排除发包，但仍 `console.log(raw.slice(0, 300))` 把完整 access_token + refresh_token 写 stdout，对 contributor 是误导。整文件移除，doc 引用同步更新。
+- **uat.js refreshUAT 错误消息不再 dump 整个响应 JSON**（`src/auth/uat.js:160-180`）：飞书部分错误路径会在响应体里 echo 回 refresh_token 字段，之前 `JSON.stringify(data)` 会把这些 bytes 抛到 Error.message → 冒泡到 MCP `content[0].text` → LLM transcript。改为只透 `data.error_description / data.msg / data.code` 结构化字段（`errCode`/`errMsg` 解构）；invalid_grant 单独走 hardcoded `'UAT refresh_token rejected by Feishu (invalid_grant). The 7-day refresh chain is broken. Run: npx feishu-user-plugin oauth to re-authorize.'`，无任何 `data` 字段 interpolation。
+- **identity-state.js `_classifyUatFailure` redact 兜底 + uatRevoked 短路**（`src/auth/identity-state.js:88-105`）：(1) 加 `if (uatError.uatRevoked) return UAT_REVOKED` 短路 —— refreshUAT 抛 invalid_grant 时设的 flag 现在真正驱动状态机（之前 flag 设了但 classifier 不读，是 dead metadata）；(2) 在 `viaReason` 拼接前用 regex `replace(/[A-Za-z0-9._-]{40,}/g, '<redacted>')` 把任何 40+ 字符的 base64-ish 串清掉。defense-in-depth on top of refreshUAT 自己的清理。两条都有 fixture 测试覆盖（test-uat-lifecycle 第 15-16 case）。
+
+### Fixed
+
+- **Cookie heartbeat 改为 ws-owner 单跑（v1.3.14 架构 root cause D 配套）**（`src/auth/cookie.js:30-50`）：pre-v1.3.14 每个 MCP server 进程独立跑自己的 4 小时 cookie heartbeat timer，10+ 个并发 Claude Code / Codex / OpenClaw session 在一台机器上意味着每 4 小时 N 倍并发请求到飞书的 session-keepalive 端点。改为 owner-gated：只有持有 `ws-owner.lock` 的进程做真实 heartbeat + 写新 cookie 到 credentials.json；非 owner 进程的 timer tick 是 no-op。非 owner client 通过 v1.3.12 的 `CredentialsMonitor.onCookieChange` hook 在下次 tool call 时自动重建 userClient 拿新 cookie。Fallback：如果 ws-owner.lock 不存在（APP_ID/SECRET 没配 → WS server 未启 → 没人 claim），所有进程都跑 heartbeat（pre-v1.3.14 行为），保证 cookie-only 部署不受影响。每次 tick 重新检查 owner 身份，ws-owner 切换时自适应。
+- **UAT refresh 跨进程锁路径迁移到 canonical home**（`src/auth/uat.js:98` `uatLockPath()`）：从 `~/.claude/feishu-uat-refresh.lock` 搬到 `~/.feishu-user-plugin/uat-refresh.lock`。原因：Codex-only 用户没有 `~/.claude/` 目录，`mkdirSync` 会隐式创建空 dir 但 lock 文件没法跨 harness 真正互斥 → 30+ MCP server 并发 lazy refresh 时绕过文件锁 → 各自发 refresh API → 飞书侧 RT rotation 抢占 → `invalid_grant` 雪崩。新路径跟 `ws-owner.lock` 同 dir，所有 harness（Claude Code / Codex / OpenClaw / scripts）走同一把锁。`scripts/test-uat-race.js` 4 worker 验证：~1500ms 串行完成，无 overlap。
+- **invalid_grant 触发 identity state machine UAT_REVOKED**（`src/auth/uat.js:170-178` + `src/auth/identity-state.js:88-95`）：refreshUAT 拿到 `error: invalid_grant` 或 `code: 20064` 时**两条路径都执行**：(1) 直接调 `_refineIdentity(client, UAT_REVOKED)` 改 cache，(2) 抛 `err.uatRevoked = true`，由 `_classifyUatFailure` 短路成 UAT_REVOKED 让 `withIdentityFallback` 后续无论谁先到都正确分类。`fallbackWarning` 从含糊的 "UAT 不可用" 升级为 "UAT 已被撤销 (invalid_grant)... 运行 `npx feishu-user-plugin oauth` 后重启"。错误消息也明确 "The 7-day refresh chain is broken"。
+- **三层 adoptPersistedUATIfNewer 检查避免重复 refresh**（`src/auth/uat.js:114-148`）：锁外预检（短路 peer 已经写过的新 token）→ 锁失败再检（lock contention 期间 peer 完成）→ 锁内再检（acquireRefreshLock 返回到自己开始 refresh 之间的窗口）。10+ MCP server 进程同时 lazy refresh 时大幅减少向飞书侧的并发请求数，进一步降低 RT rotation 冲撞。
+- **withUAT retry 后也走 auth-code 检查**（`src/auth/uat.js:194`）：第一次 fn() 抛网络错时 `classifyError` 说 retry，**之前** retry 结果直接 return；**现在**让 retry 后的 response 也通过 `data.code === 99991663/99991668/99991677` 判断，触发 refresh 后再 retry。fix 一个静默走漏：peer 进程在 retry 间隙做了 RT rotation 后，本进程内存 RT 失效，retry response 携带 auth-related code 之前不会触发 refresh。
+- **OAuth + setup 所有 `fetch` 调用加 `timeoutMs`**（`src/oauth.js` 4 处 + `src/setup.js:106`）：之前裸 `fetch`，socket 卡死会让 `npx oauth` / `npx setup` 永久挂。Ctrl-C 重跑同一 authorization code 已被消费必失败。改为 `fetchWithTimeout` with 10-15s timeout。
+- **scripts/test-uat-race-child.js 修复跨进程 race 测试**（v1.3.7 静默坏掉）：原 child 调用 `client._uatLockPath() / _acquireRefreshLock()`，但 v1.3.7 phase A 把这些方法从 `LarkOfficialClient` 抽到 `src/auth/uat.js` 模块。pre-fix child 启动即 `TypeError`，4 个 worker 全部失败但 race test 报 `expected 4 successful workers, got 0` 时大家以为是环境问题。改为直接 import `uat.js::uatLockPath / acquireRefreshLock / releaseRefreshLock`。
+- **credentials-monitor.js `forceInvalidate` 在 canonical 不存在时 `_initialized` 没翻转**（`src/auth/credentials-monitor.js:177`）：之前 `_initialized` 只在 sync() 内部 set；forceInvalidate 时如果 canonical 不存在（用户手动删/移动文件），`_initialized` 仍是 false → 下次 sync() 文件出现会被当 baseline → 应该 fire 的 hook 被静默吞掉。修法：forceInvalidate 末尾无条件 `_initialized = true`。
+- **server.js Lark Desktop reactor 冷启动 debounce**（`src/server.js:86-89` + `_runLarkDesktopReactor` first-tick init）：之前 `_lastSwitchAt = 0` module-global，长时间运行的 owner 进程突然死掉后新 owner 接管，新 owner 的 `_lastSwitchAt` 是 0 → detectSwitch debounce 失效 → 冷启动第一次 tick 会把长期 pre-existing 的 Lark Desktop snapshot 当 "刚刚切换" 误触发 profile flip。修法：reactor 首次 tick 时若 `_lastSwitchAt === 0` 自动 stamp 为 `Date.now()`，给冷启动跟长跑 owner 一样的 debounce baseline。
+- **decodeTokenExpiry 失败 breadcrumb flood-gate**（`src/auth/uat.js:31-46`）：之前每次 `getValidUAT` 调用都会 decode `_uat`（因为 `_uatExpires = 0` 在解码失败后还是 falsy → 下次又 decode），如果 token 持续 malformed 会每个 tool 调用都向 stderr 打一行 warning。改为按 token sha256 hash 去重：每个 distinct 坏 token 只打一次，1024 entry cap 防 OOM。两个新 test case 验证 "same bad token 5 次只 log 1 次" + "3 个不同 bad token 各 log 1 次"。
+
+### Changed
+
+- **`LarkOfficialClient.loadUAT()` 标 `@deprecated` + 内部简化**（`src/clients/official/base.js:25-35`）：保留向后兼容 `src/test-all.js` 与外部 caller；新代码统一走 `src/server.js::loadUATFromEnv(client, env)` 从 credentials.json profile 或 harness env 读，不读 `process.env`。函数体也清掉了 v1.3.13 留下的死表达式（`parseInt(token ? ... : '0')` 表面像 guard 实际无效，code-review 期间删干净）。`server.js` 旁边的 "Mirror of LarkOfficialClient.loadUAT()" 注释更新成正向描述。
+- **`cli.js keepalive` 不再污染 `process.env`**（`src/cli.js:251`）：之前 `--all` 循环里写 `process.env.LARK_USER_ACCESS_TOKEN` 但不还原。注释还说"让 LarkOfficialClient.loadUAT() picks the right tokens"，但实际 loadUAT 没被调用（v1.3.7 起 keepalive 直接赋实例字段）—— 既是 dead 操作又是 dead 注释。删干净。
+- **`src/test-all.js` 自动从 canonical store backfill `process.env`**：v1.3.7+ 用户走 canonical store 后 `process.env.LARK_*` 多半为空，`npm test` 入口的 cookie / UAT 初始化会 sanity fail。加 `backfillFromCanonical()` 让 `npm test` 在没 export env vars 的 shell 直接跑通。
+
+### Added
+
+- **新测试套件 `src/test-uat-lifecycle.js`（18 个 case）**：unit + mock-fetch，覆盖 decodeTokenExpiry（well-formed / missing payload / malformed base64 / no exp / flood-gate same-token-only-warns-once / flood-gate different-tokens-each-warn-once）、acquireRefreshLock（fresh / contention timeout / stale recovery）、releaseRefreshLock 容忍重复释放、adoptPersistedUATIfNewer（no canonical / same token / newer access / rotated refresh）、refreshUAT（invalid_grant 抛 `err.uatRevoked=true`、99991663 transient 不设 uatRevoked）、identity-state `_classifyUatFailure`（redact regex 真实 exercise long token-like string、uatRevoked flag 短路成 UAT_REVOKED）。接入 `npm test` 进 PR gate。
+- **新测试套件 `src/test-cookie-heartbeat.js`（9 个 case）**：覆盖 `_isHeartbeatRunner` 在 6 种 lock 状态（ws-owner=self / ws-owner=other / lock missing / lock body malformed / pid 缺失 / pid 类型错）+ `_heartbeatTick` 在 3 种 owner 状态下的实际调用决策（non-owner 跳过、owner 成功 refresh + persist、owner network 失败但不 persist 不抛）。`_heartbeatTick` 函数从原 `setInterval` callback 抽出，让 tick path 可在 unit 测里直接 invoke 不必等 4 小时 timer。接入 `npm test`。
+- **`src/auth/uat.js` 新增 export `uatLockPath / acquireRefreshLock / releaseRefreshLock`**：仅供测试 harness 用（明确标注非稳定 API），让 lifecycle test + cross-process race test 不依赖 client 实例方法。
+- **`src/auth/identity-state.js` 新增 export `_classifyUatFailure`**：仅供测试用，让 redact regex + uatRevoked short-circuit 两条路径直接被 fixture 测到。
+- **`src/auth/env-backfill.js`（新文件）**：从 canonical credentials store backfill `process.env.LARK_*`，给 legacy 路径（`loadUAT()` 读 `process.env`）兜底。提取自 v1.3.14 初版加在 `test-all.js` 顶部的 closure；现在被 `test-all.js` / `test-comprehensive.js` / `scripts/probe-feishu-docx.js` / `scripts/test-wiki-attach-fallback.js` 共用，统一 6 个 `LARK_*` keys backfill 范围（之前 `probe-feishu-docx.js` 只 backfill 2 key，缺 `LARK_UAT_EXPIRES`；现在统一）。`shell-export LARK_* > .env > canonical` 的优先级保留。
+
+### Docs
+
+- **`docs/TROUBLESHOOTING.md` 加 4 个高频 troubleshooting 段**：（1）"频繁收到飞书授权操作通知" —— 给 JWT `auth_time` 字段诊断命令 + 区分 fresh consent vs silent refresh vs 飞书 server 侧策略变化；（2）"Token 已过期但 MCP 没自动刷新" —— uat-refresh.lock stale 检查 + canonical store 校验 + manual `keepalive`；（3）"v1.3.14 升级期间混合版本（短暂窗口）" —— 旧 v1.3.13 + 新 v1.3.14 同时跑 5 分钟内的 lock 路径不对齐风险 + 恢复步骤；（4）"migrate 后老 env 凭证还在被读" —— 重启 + 清 stale fallback 字段步骤。`UAT refresh invalid_grant` 现有段补 v1.3.14 锁路径变化说明 + canonical hot-reload 期望。
+- **`README.md:147` "已删除" 条目补 reason inline**：之前只写"详见 ROADMAP"，现在显式说明 md → wiki 因 wiki block schema 离散度高、Mermaid → 画板因依赖 wiki 主线一并删，不必跳出 README 就能理解。
+- **`src/auth/cookie.js` 文件头注释精简**（17 行 → 7 行）：保留核心机制说明（owner-gated + non-owner reload path + fallback），删掉营销腔的"10+ concurrent" 阐述（CHANGELOG 已有详述）。
+- **`src/error-codes.js:31` 注释 "30-day window" → "7-day refresh-token window"**：飞书 v2 OAuth refresh_token 实际寿命 7 天滚动续期（与 `docs/AUTH-SETUP.md:29` / `docs/COMPARISON.md:52` / `src/oauth.js:255` 浏览器回调文案对齐）。这一处历史错文档跟其他 doc 一直矛盾，本版收口。
+- **`README.md:147` 删除 "未实现：search_messages"**：v1.3.12 已实装，CLAUDE.md 当时改了但 README 漏改。换成 "已删除：md → wiki 双向同步、Mermaid → 画板"。
+- **`docs/AUTH-SETUP.md:30` ws-owner.lock stale 时长 "30 秒" → "60 秒"**：与 `src/events/owner.js:14 STALE_MS = 60_000` 实际值对齐 + 补 v1.3.12 PID liveness check 说明（SIGKILL'd owner 即时回收，不必等 mtime）。同段加新行：`~/.feishu-user-plugin/uat-refresh.lock`（v1.3.14 起）+ 历史路径备注。
+- **`src/oauth.js:255` 浏览器回调 HTML 文案 "30天有效" → "7天有效，每次 refresh 滚动续 7 天"**：澄清滚动续期语义 —— 活跃用户的 refresh_token 永远不过期，`keepalive` cron 只为关闭客户端 >7 天的场景。
+- **`SECURITY.md:58` + `prompts/openclaw-setup.md:36` lock path 同步更新**：跟 v1.3.14 canonical 路径一致 + 保留历史路径备注。
+- **`docs/REFACTOR-NOTES.md:29` 删除 `oauth-auto.js` 引用**：随文件删除，行内说明改成 `OAuth CLI 流程（v1.3.14 起 oauth-auto.js Playwright helper 已删除）`。
+- **`prompts/openclaw-setup.md:34` 工具数 "84 个" → "85 个"**：跟主仓 README + SKILL.md 已经标的 85 对齐，pre-existing drift 顺手收口。
+- **`prompts/openclaw-setup.md:36` 升级命令 "更新到 1.3.14" → "`npm i -g feishu-user-plugin@latest`"**：避免每发新版本都得回头改这条 dev doc。
+- **`ROADMAP.md` 标题 "v1.3.13+ 待办" → "v1.3.14+ 待办"**。
+- **`docs/RELEASING.md` Step 2 明确列出 6 处版本号 bump**：之前文档说"4 个，mcp-registry + mcpb 由 check 脚本单独校验"——这表述让 v1.3.14 release 漏了这 2 个 bump 直到 CI 警告才发现。改为显式列 6 处 + 各 check 脚本范围，避免后续 release 重蹈覆辙。
+
+### Release engineering
+
+- **6 个版本号 source 全 bump**：`package.json` / `.claude-plugin/plugin.json` / `.cursor-plugin/plugin.json` / `skills/feishu-user-plugin/SKILL.md` / `mcp-registry.json`（含 `packages[0].version`） / `.mcpb/manifest.json`。`server.json` 由 `sync-server-json.js` regen。
+- **10 个 CI gate 全通**：`check-version` / `check-tool-count` / `check-description-drift` / `check-mcp-registry-version` / `check-mcpb-version` / `sync-server-json` / `check-changelog` / `check-scopes` / `check-broken-links` / `check-docs-sync`（validate.yml + publish.yml + prepublishOnly 三个 workflow 跑全套）。
+
+### Test scenarios
+
+- `npm test`（在没有 export `LARK_*` env vars 的 shell）→ **83 个 fixture pass / 0 fail**（含 e2e 18 PASS / 15 SKIP / 0 FAIL + test-uat-lifecycle 18 + test-cookie-heartbeat 9 + lark-desktop 13 + display-label 8 + 既有命名单元 17）
+- OAuth 流程浏览器回调页面 source view → access_token 行只显示 `✅ 已获取（N chars）` 不含任何 token byte
+- 触发持续 malformed UAT 场景（手动 corrupt token in canonical, 调 N 个 UAT 工具）→ stderr 只一条 `decodeTokenExpiry: malformed JWT` 警告，N-1 条被 dedupe
+- `node scripts/test-uat-race.js`（4 worker 跨进程抢锁）→ **mutual exclusion PASSED**，4 worker 串行 ~1500ms，无 overlap（典型 1500-1520ms，依赖系统负载；4 × 300ms hold + 调度开销）
+- `node scripts/check-scopes.js` → `OK (31 OAuth + 1 tenant-only scopes, 2 banned names guarded)`
+- `npm run smoke` → `OK: 85 tools, 9 prompts, login_status shape matches`
+- `npx feishu-user-plugin oauth` 之后浏览器页面文案：`refresh_token: ✅ 已获取（7天有效，支持自动续期；每次 refresh 滚动续 7 天）`
+- 模拟 invalid_grant：next UAT tool call 的 `_fallbackWarning` 包含 `UAT 已被撤销 (invalid_grant)... 运行 \`npx feishu-user-plugin oauth\` 后重启`
+- 升级后短暂出现 `~/.feishu-user-plugin/uat-refresh.lock`（refresh 时；30 秒 stale 自动回收）
+
 ## [1.3.13] - 2026-05-16
 
 紧急 patch — v1.3.12 release 后 Codex + Copilot PR #103 review 发现 1 P1 + 2 P2 + 5 polish，followup 又跑 5-agent 全仓 audit 找出 2 P1 (security) + 多个 doc/compliance 漂移。本版集中修复全部 issue + 把 fixture-based unit tests 拉进 CI gate。

package/README.en.md

@@ -13,7 +13,9 @@ Feishu / Lark MCP server covering IM, docs, bitable, wiki, drive, calendar, task
 
 Works with Claude Code, Codex, Cursor, Windsurf, VS Code, Claude Desktop, OpenClaw, and any MCP-compatible client.
 
-There are two paths to user-identity messaging: **Feishu's official OAuth scope `im:message.send_as_user`** (requires creating a self-built app + admin approval), or this repo's **cookie + protobuf path** (zero app barrier — capture cookie and you're ready). This repo is no longer architecturally exclusive, but it remains the simpler option for "individual developers / no admin access / want to try quickly" scenarios.
+For user-identity messaging there are two paths: **Feishu's official OAuth scope `im:message.send_as_user`** (requires creating a self-built app + admin approval), or this repo's **cookie + protobuf path** (capture cookie and you're ready). This repo is no longer architecturally exclusive, but it remains the simpler option for "individual developers / no admin access / want to try user-identity messaging quickly" scenarios.
+
+> ⚠ **Scope of the zero-app-barrier claim**: only **text / post user-identity messaging** is strictly app-free: `send_to_user` / `send_to_group` / `send_as_user` / `send_post_as_user` / `batch_send` (text/post mode) — 5 tools. `send_image_as_user` / `send_file_as_user` send via cookie, but `image_key` / `file_key` must first be uploaded through the Official API (`upload_image` / `upload_file`); `send_card_as_user` is server-blocked on the cookie channel and always routes through bot. All other capabilities in this repo (reading group messages, document / bitable / wiki / drive / calendar / tasks / OKR / realtime events) **still require a Feishu self-built app** (`LARK_APP_ID` + `LARK_APP_SECRET`) — same as the official MCP / CLI.
 
 ## vs the official Feishu/Lark tools (released 2026)
 

package/README.md

@@ -13,7 +13,9 @@
 
 兼容 Claude Code、Codex、Cursor、Windsurf、VS Code、Claude Desktop、OpenClaw 等 MCP 客户端。
 
-用户身份发消息有两条路径：**飞书官方 OAuth scope `im:message.send_as_user`**（需要创建自建应用 + 管理员审批），或本仓的 **cookie + protobuf 路径**（零应用门槛，cookie 抓出来就跑）。本仓不再是物理性独家，但仍然是"个人开发者 / 没有管理员权限 / 想快速试"场景的简便选项。
+用户身份发消息有两条路径：**飞书官方 OAuth scope `im:message.send_as_user`**（需要创建自建应用 + 管理员审批），或本仓的 **cookie + protobuf 路径**（cookie 抓出来就跑）。本仓不再是物理性独家，但仍然是"个人开发者 / 没有管理员权限 / 想快速试用户身份发消息"场景的简便选项。
+
+> ⚠ **注意限定范围**：cookie 路径"零应用门槛"只对**纯文本 / post 类用户身份发消息**严格成立：`send_to_user` / `send_to_group` / `send_as_user` / `send_post_as_user` / `batch_send`（text/post 模式）5 个工具。`send_image_as_user` / `send_file_as_user` 的发送本身走 cookie，但 `image_key` / `file_key` 必须先经 Official API（`upload_image` / `upload_file`）上传；`send_card_as_user` 服务端禁了 cookie 通道，始终走 bot。本仓其他能力（读群消息、操作文档 / 表格 / 知识库 / 云空间 / 日历 / 任务 / OKR / 实时事件等）也**仍然需要创建飞书自建应用**（`LARK_APP_ID` + `LARK_APP_SECRET`），跟官方 MCP / CLI 完全一样。
 
 ## 与官方对比（飞书 2026 年也发了 MCP + CLI）
 
@@ -142,7 +144,7 @@ mcp call manage_ws_status --action claim --force true
 - **协议变化**：cookie + protobuf 层依赖飞书 web 客户端的协议，飞书更新可能失效（机器人能力不受影响）
 - **卡片**：cookie 通道发卡片服务端不可用，机器人通道可发
 - **Lark 国际版**：实时事件 WS 不支持
-- **未实现**：`search_messages`、md → wiki 同步（详见 [ROADMAP.md](ROADMAP.md)）
+- **已删除**：md → wiki 双向同步（飞书 wiki block schema 离散度高，无损往返不现实）、Mermaid → 飞书画板（依赖 wiki 主线一并删）。详见 [ROADMAP.md](ROADMAP.md) 的"已删除"段
 
 ## 文档
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
   "mcpName": "io.github.EthanQC/feishu-user-plugin",
-  "version": "1.3.13",
+  "version": "1.3.14",
   "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/check-broken-links.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+'use strict';
+// Scans tracked .md files for broken intra-repo file links.
+//
+// Checks only whether the target FILE exists on disk. Does NOT verify
+// section anchors (GitHub's anchor-slug algorithm has CJK / em-dash
+// edge cases that produce too many false positives to be worth the
+// gate's signal). If you rename a heading and a link's #anchor stops
+// working, GitHub renders the link clickable but lands at the page
+// top — annoying but not broken in the structural sense.
+//
+// Checks:
+//   - [text](path/to/file.md) — relative or absolute path within the repo
+//   - [text](./file.md) / [text](../file.md) — relative paths
+//
+// Skips:
+//   - http:// / https:// links (external URLs not verified)
+//   - mailto: / # (pure page-internal anchors)
+//   - Image links ![...](...)
+//   - Targets that don't end in a file extension (e.g. "知乎专栏链接",
+//     "wikcnXXX", "args, ctx") — these are placeholder text inside
+//     markdown link syntax, not real file paths
+//   - Files under docs/launch/ + docs/superpowers/ (staging / historical
+//     plan docs — placeholder text + draft links are intentional there)
+//
+// Why this gate exists: PR-H series consolidated cross-link style
+// (relative paths in docs/* and README, GitHub URLs in CLAUDE.md /
+// AGENTS.md). Without this gate, future PRs can silently break links
+// when files are renamed.
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const ROOT = path.join(__dirname, '..');
+
+// Tracked .md files
+const allFiles = execSync('git ls-files "*.md"', { cwd: ROOT, encoding: 'utf8' })
+  .trim()
+  .split('\n')
+  .filter(Boolean);
+
+// Skip staging / historical-plan directories — links there are often
+// intentional placeholders for content yet to be written.
+const SKIP_DIRS = ['docs/launch/', 'docs/superpowers/'];
+const files = allFiles.filter(f => !SKIP_DIRS.some(d => f.startsWith(d)));
+
+const failures = [];
+
+// Pattern: [link text](target) — but not preceded by `!` (image)
+const LINK_RE = /(?<!!)\[([^\]]+)\]\(([^)]+)\)/g;
+
+// Heuristic: real file paths have a file extension (.md, .png, .json, ...) or
+// they're a directory reference. Anything else is treated as placeholder text.
+const FILE_EXT_RE = /\.[a-zA-Z0-9]{1,8}(#|$)/;
+
+// Skip .html targets — Jekyll Pages cross-page links (`./en.html`) point at
+// HTML produced by jekyll-build, not source files in the repo. The .html
+// equivalent doesn't exist on disk but works at runtime on the rendered site.
+const JEKYLL_HTML_RE = /\.html(#|$)/;
+
+// Strip code blocks (``` ... ``` and `inline`) so we don't false-positive
+// on markdown link syntax that appears inside code examples.
+function stripCode(content) {
+  return content
+    .replace(/```[\s\S]*?```/g, '')   // fenced
+    .replace(/`[^`\n]+`/g, '');       // inline
+}
+
+for (const file of files) {
+  const content = stripCode(fs.readFileSync(path.join(ROOT, file), 'utf8'));
+  const dir = path.dirname(file);
+
+  for (const m of content.matchAll(LINK_RE)) {
+    const linkTarget = m[2].trim();
+
+    // Skip external URLs and mailto/etc
+    if (/^[a-z]+:\/\//i.test(linkTarget) || linkTarget.startsWith('mailto:')) continue;
+    // Skip pure page-internal anchors
+    if (linkTarget.startsWith('#')) continue;
+    // Skip targets that don't look like file paths (placeholder text)
+    if (!FILE_EXT_RE.test(linkTarget) && !linkTarget.endsWith('/')) continue;
+    // Skip Jekyll-rendered .html links (cross-page in docs/index.md / en.md)
+    if (JEKYLL_HTML_RE.test(linkTarget)) continue;
+
+    // Strip anchor portion if present
+    const pathPart = linkTarget.split('#')[0];
+    if (!pathPart) continue;
+
+    // Resolve target: leading `/` means repo-absolute (rare but valid in
+    // markdown); otherwise resolve relative to the source file's directory.
+    // path.resolve handles `..` and normalizes; the boundary check below
+    // rejects targets that escape ROOT.
+    const absoluteResolved = pathPart.startsWith('/')
+      ? path.resolve(ROOT, pathPart.replace(/^\/+/, ''))
+      : path.resolve(ROOT, dir, pathPart);
+
+    if (absoluteResolved !== ROOT && !absoluteResolved.startsWith(ROOT + path.sep)) {
+      failures.push(`${file}: broken link "${linkTarget}" — target escapes repo root`);
+      continue;
+    }
+
+    if (!fs.existsSync(absoluteResolved)) {
+      const rel = path.relative(ROOT, absoluteResolved);
+      failures.push(`${file}: broken link "${linkTarget}" — file "${rel}" does not exist`);
+    }
+  }
+}
+
+if (failures.length) {
+  console.error(`Broken markdown file links detected (${failures.length}):`);
+  for (const f of failures) console.error(`  ${f}`);
+  console.error('\nFix: update the path in the source .md, or rename / restore the referenced file.');
+  process.exit(1);
+}
+
+console.log(`OK: scanned ${files.length} .md files (excluding ${SKIP_DIRS.join(' / ')}), no broken intra-repo file links`);

package/scripts/generate-release-artifacts.js

@@ -303,7 +303,13 @@ function main() {
   const teamSkillsBlock = generateTeamSkillsChangelog(version, date, parsed, null);
   fs.writeFileSync(path.join(outDir, 'team-skills-changelog.md'), teamSkillsBlock);
 
-  const rootRow = generateRootReadmeRow(version, pkg.description);
+  // Use .claude-plugin/plugin.json::description (NOT package.json), because
+  // team-skills' own scripts/generate-readme.py reads each plugin's
+  // .claude-plugin/plugin.json::description. Mismatch causes team-skills
+  // CI "Validate Plugins" to fail (caught 2026-05-13 root-cause analysis:
+  // 7 of last 30 team-skills CI runs failed for exactly this drift).
+  const pluginJson = JSON.parse(fs.readFileSync(path.join(ROOT, '.claude-plugin', 'plugin.json'), 'utf8'));
+  const rootRow = generateRootReadmeRow(version, pluginJson.description);
   fs.writeFileSync(path.join(outDir, 'team-skills-readme-row.md'), rootRow + '\n');
 
   const card = generateCard(version, date, parsed);

package/scripts/probe-feishu-docx.js

@@ -83,12 +83,12 @@ const BLOCK_LABELS = {
     process.exit(1);
   }
   const c = new LarkOfficialClient(env.LARK_APP_ID, env.LARK_APP_SECRET);
-  // loadUAT() reads process.env directly — propagate if we got tokens from
-  // the .claude.json fallback path, where process.env is not populated.
-  for (const k of ['LARK_USER_ACCESS_TOKEN', 'LARK_USER_REFRESH_TOKEN']) {
-    if (env[k] && !process.env[k]) process.env[k] = env[k];
-  }
-  if (env.LARK_USER_ACCESS_TOKEN) c.loadUAT();
+  // loadUAT() reads process.env directly. v1.3.14 — use the shared backfill
+  // helper instead of the inline 2-key copy this script previously did
+  // (LARK_UAT_EXPIRES was missing from the manual loop, leading to silent
+  // token-expires-zero issues on the probe path).
+  require('../src/auth/env-backfill').backfillFromCanonical();
+  if (process.env.LARK_USER_ACCESS_TOKEN) c.loadUAT();
 
   // --- Fetch blocks ---
   // NOTE: getDocBlocks fetches up to 500 blocks (no pagination). Docs longer

package/scripts/test-uat-race-child.js

@@ -1,17 +1,20 @@
 // Child worker for test-uat-race.js. Acquires the UAT refresh lock, holds
 // for a brief window (simulating the refresh + persist), then releases.
 // Writes a single line to stdout: "<id> acquired <ts_ms>; released <ts_ms>"
+//
+// v1.3.14 — rewritten to use module-level uat.js API. Pre-v1.3.14 this called
+// `client._uatLockPath()` etc, which no longer existed after v1.3.7 extracted
+// lifecycle into src/auth/uat.js — the test was silently broken for months.
 
-const { LarkOfficialClient } = require('../src/official');
+const { uatLockPath, acquireRefreshLock, releaseRefreshLock } = require('../src/auth/uat');
 
 const id = process.argv[2] || '?';
 const holdMs = parseInt(process.argv[3] || '250');
 
-const client = new LarkOfficialClient('test', 'test');
-const lockPath = client._uatLockPath();
+const lockPath = uatLockPath();
 
 (async () => {
-  const got = await client._acquireRefreshLock(lockPath, { timeoutMs: 15000 });
+  const got = await acquireRefreshLock(lockPath, { timeoutMs: 15000 });
   if (!got) {
     console.log(`${id} FAILED_TO_ACQUIRE`);
     process.exit(1);
@@ -19,6 +22,6 @@ const lockPath = client._uatLockPath();
   const acquired = Date.now();
   await new Promise(r => setTimeout(r, holdMs));
   const released = Date.now();
-  client._releaseRefreshLock(lockPath);
+  releaseRefreshLock(lockPath);
   console.log(`${id} acquired ${acquired}; released ${released}`);
 })().catch(e => { console.log(`${id} ERROR ${e.message}`); process.exit(1); });

package/scripts/test-uat-race.js

@@ -12,11 +12,18 @@ const HOLD_MS = 300;
 
 const child = path.join(__dirname, 'test-uat-race-child.js');
 
-// Clean up any stale lock from prior runs
+// Clean up any stale lock from prior runs.
+// v1.3.14 — lock path moved; clean up both old and new locations in case the
+// test runs against either version.
+try {
+  const os = require('os');
+  fs.unlinkSync(path.join(os.homedir(), '.feishu-user-plugin', 'uat-refresh.lock'));
+  console.log('(cleaned up stale lock at canonical path)');
+} catch (_) {}
 try {
   const os = require('os');
   fs.unlinkSync(path.join(os.homedir(), '.claude', 'feishu-uat-refresh.lock'));
-  console.log('(cleaned up stale lock)');
+  console.log('(cleaned up stale lock at legacy path)');
 } catch (_) {}
 
 (async () => {

package/scripts/test-wiki-attach-fallback.js

@@ -15,6 +15,13 @@ if (!creds.LARK_APP_ID || !creds.LARK_APP_SECRET || !creds.LARK_USER_ACCESS_TOKE
   process.exit(77); // POSIX skip code
 }
 
+// v1.3.14 — `loadUAT()` reads from process.env, but `readCredentials()` reads
+// from canonical store or harness env. Without backfill, the early-skip guard
+// above would pass (creds has the UAT) but loadUAT() below would silently
+// no-op (process.env doesn't), so the test would run with an empty UAT
+// against the mocked-attachToWiki path.
+require('../src/auth/env-backfill').backfillFromCanonical();
+
 (async () => {
   const { LarkOfficialClient } = require('../src/clients/official');
   const client = new LarkOfficialClient(creds.LARK_APP_ID, creds.LARK_APP_SECRET);

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

@@ -1,7 +1,7 @@
 ---
 name: feishu-user-plugin
-version: "1.3.13"
-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.13: search_messages tool (Protobuf phase 2, UAT-only), CLI tool mode (tool list / help / dispatch), IdentityState state machine + credentials hot-reload (UAT viaUser flag preserved across the 15+ write tools, no-restart UAT/cookie reload, startup-blind-window closed), displayLabel + sender semantics pack, WS owner PID liveness, gitleaks secret scan, oauth.js token-leak hardening, fixture unit tests pulled into CI gate."
+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)."
 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/src/auth/cookie.js

@@ -1,22 +1,69 @@
 // src/auth/cookie.js — cookie heartbeat scheduler.
 //
-// State lives on the LarkUserClient instance (this.cookieStr, this._heartbeatTimer).
-// We expose start/stop functions that take `client` and mutate the timer field.
-// Lifted out of clients/user.js for clarity; called only from there.
+// State lives on the LarkUserClient instance. Lifted from clients/user.js.
+//
+// v1.3.14 — owner-gated single runner: only the process holding
+// ws-owner.lock does the real heartbeat; non-owners tick into no-op. Non-owner
+// clients pick up the refreshed cookie via CredentialsMonitor's
+// onCookieChange hook on the next tool call. Fallback: no ws-owner.lock
+// (e.g., APP_ID/SECRET missing → no WS server) → every process runs heartbeat
+// (pre-v1.3.14 behaviour), keeping cookie-only deployments working.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 
 const HEARTBEAT_INTERVAL_MS = 4 * 60 * 60 * 1000; // 4 hours — sl_session has 12h max
+const WS_OWNER_LOCK = path.join(os.homedir(), '.feishu-user-plugin', 'ws-owner.lock');
+
+/**
+ * Returns true iff this process should run the cookie heartbeat right now.
+ * Logic: this process is the ws-owner, OR no ws-owner exists (fallback).
+ * Re-checked on every tick so the gate adapts to live ws-owner takeovers.
+ *
+ * Exported for testing — callers should not depend on its presence.
+ */
+function _isHeartbeatRunner(_lockPath = WS_OWNER_LOCK, _pid = process.pid) {
+  let body;
+  try {
+    body = JSON.parse(fs.readFileSync(_lockPath, 'utf8'));
+  } catch (_) {
+    // Lock file missing or unreadable → no owner is claimed → fall back to
+    // pre-v1.3.14 behavior (every process runs heartbeat).
+    return true;
+  }
+  if (typeof body.pid !== 'number') return true; // malformed body → fallback
+  return body.pid === _pid;
+}
+
+/**
+ * One heartbeat tick. Extracted so unit tests can call it directly without
+ * waiting 4 hours. Returns the action taken: 'skip' (non-owner), 'refreshed'
+ * (owner did the API call + persist), or 'error' (owner tried but failed).
+ *
+ * Exported for testing.
+ */
+async function _heartbeatTick(client, deps = {}) {
+  const isOwner = deps.isHeartbeatRunner || _isHeartbeatRunner;
+  if (!isOwner()) {
+    return 'skip';
+  }
+  try {
+    await client._getCsrfToken();
+    const persist = deps.persistToConfig || require('./credentials').persistToConfig;
+    persist({ LARK_COOKIE: client.cookieStr });
+    console.error('[feishu-user-plugin] Cookie heartbeat: session refreshed and persisted (ws-owner)');
+    return 'refreshed';
+  } catch (e) {
+    console.error('[feishu-user-plugin] Cookie heartbeat failed:', e.message);
+    return 'error';
+  }
+}
 
 function startHeartbeat(client) {
-  client._heartbeatTimer = setInterval(async () => {
-    try {
-      await client._getCsrfToken();
-      const { persistToConfig } = require('./credentials');
-      persistToConfig({ LARK_COOKIE: client.cookieStr });
-      console.error('[feishu-user-plugin] Cookie heartbeat: session refreshed and persisted');
-    } catch (e) {
-      console.error('[feishu-user-plugin] Cookie heartbeat failed:', e.message);
-    }
-  }, HEARTBEAT_INTERVAL_MS);
+  client._heartbeatTimer = setInterval(() => _heartbeatTick(client), HEARTBEAT_INTERVAL_MS);
   if (client._heartbeatTimer.unref) client._heartbeatTimer.unref();
 }
 
@@ -27,4 +74,10 @@ function stopHeartbeat(client) {
   }
 }
 
-module.exports = { startHeartbeat, stopHeartbeat, HEARTBEAT_INTERVAL_MS };
+module.exports = {
+  startHeartbeat,
+  stopHeartbeat,
+  HEARTBEAT_INTERVAL_MS,
+  _isHeartbeatRunner, // exported for testing
+  _heartbeatTick,     // exported for testing
+};

package/src/auth/credentials-monitor.js

@@ -170,6 +170,11 @@ function createCredentialsMonitor({ path: credPath = DEFAULT_PATH } = {}) {
       lastRefreshHash = _fieldHash(env, 'LARK_USER_REFRESH_TOKEN');
       lastMtimeMs = stat.mtimeMs;
     }
+    // v1.3.14 — always mark initialized after forceInvalidate, even when
+    // canonical was null. Without this, a subsequent sync() that finds the
+    // file existing would treat the first read as baselining (silent) and
+    // swallow the hook fire that should signal "file appeared".
+    _initialized = true;
   }
 
   return {

package/src/auth/env-backfill.js

@@ -0,0 +1,37 @@
+// src/auth/env-backfill.js — backfill `process.env.LARK_*` from canonical
+// credentials store, for legacy callers that read env directly.
+//
+// Motivation: v1.3.7+ canonical store is at ~/.feishu-user-plugin/credentials.json,
+// but the original CLI flows + e2e tests + dev probes (e.g. test-all.js,
+// test-comprehensive.js, scripts/probe-feishu-docx.js, scripts/test-wiki-attach-
+// fallback.js) constructed clients with `process.env.LARK_*`. After users move
+// creds to canonical, those env vars are empty in a fresh shell and the legacy
+// paths fall over.
+//
+// This helper sets process.env values from canonical if and only if they aren't
+// already set, preserving precedence: explicit shell env > canonical fallback.
+// Safe to call multiple times — idempotent. Safe to call before canonical
+// exists (no-op, legacy harness env still wins).
+
+'use strict';
+
+const SNAP_KEYS = [
+  'LARK_COOKIE',
+  'LARK_APP_ID',
+  'LARK_APP_SECRET',
+  'LARK_USER_ACCESS_TOKEN',
+  'LARK_USER_REFRESH_TOKEN',
+  'LARK_UAT_EXPIRES',
+];
+
+function backfillFromCanonical() {
+  try {
+    const { readCredentials } = require('./credentials');
+    const creds = readCredentials();
+    for (const k of SNAP_KEYS) {
+      if (!process.env[k] && creds[k]) process.env[k] = String(creds[k]);
+    }
+  } catch (_) { /* canonical may not exist; legacy path unaffected */ }
+}
+
+module.exports = { backfillFromCanonical, SNAP_KEYS };

package/src/auth/identity-state.js

@@ -84,7 +84,22 @@ function _refineIdentity(client, state) {
 // should keep the original VALID_USER state and just record the via_reason).
 function _classifyUatFailure(uatResp, uatError) {
   if (uatError) {
-    const msg = uatError.message || String(uatError);
+    // v1.3.14 — explicit short-circuit when refreshUAT set `err.uatRevoked`.
+    // Lets refresh-side rejections (invalid_grant from /authen/v2/oauth/token)
+    // flow into the same UAT_REVOKED state as tool-call-side 20064 responses,
+    // and lets `withIdentityFallback` build a clear "请重跑 oauth" warning.
+    if (uatError.uatRevoked) {
+      return {
+        state: IdentityState.UAT_REVOKED,
+        viaReason: 'as user: refresh_token rejected by Feishu (invalid_grant)',
+      };
+    }
+    // v1.3.14 — redact base64-ish tokens (40+ chars of [A-Za-z0-9._-]) in
+    // case an upstream throw site leaked refresh_token or access_token bytes
+    // into the error message. Defense-in-depth on top of uat.js::refreshUAT
+    // which already avoids dumping the raw response body.
+    const rawMsg = uatError.message || String(uatError);
+    const msg = rawMsg.replace(/[A-Za-z0-9._-]{40,}/g, '<redacted>');
     // Network/JSON parse errors don't refine identity — UAT is still presumed
     // valid, we just couldn't reach Feishu this call.
     return { state: null, viaReason: `as user: ${msg}` };
@@ -206,4 +221,5 @@ module.exports = {
   invalidateIdentity,
   _refineIdentity, // exported for D's CredentialsMonitor hook (private API)
   _readInMemoryState, // exported for testing edge cases (private API)
+  _classifyUatFailure, // v1.3.14 — exported for testing redact + uatRevoked wiring
 };