feishu-user-plugin 1.3.11 → 1.3.12

package/scripts/check-tool-count.js

@@ -6,11 +6,12 @@ const { TOOLS } = require(path.join(__dirname, '..', 'src', 'server'));
 
 const failures = [];
 
-// Source 1: README.md "N tools" badge
+// Source 1: README.md tool count — accepts "N tools" (English) or "N 工具" (Chinese)
+// since README.md is Chinese-primary while README.en.md mirrors in English.
 const readme = fs.readFileSync(path.join(__dirname, '..', 'README.md'), 'utf8');
-const readmeMatch = readme.match(/(\d+)\s+tools/);
+const readmeMatch = readme.match(/(\d+)\s*(?:tools|工具)/);
 if (!readmeMatch) {
-  failures.push('No "N tools" badge in README.md');
+  failures.push('No "N tools" / "N 工具" marker in README.md');
 } else if (parseInt(readmeMatch[1], 10) !== TOOLS.length) {
   failures.push(`README.md claims ${readmeMatch[1]} tools, src/server.js has ${TOOLS.length}`);
 }

package/scripts/sync-claude-md.sh

@@ -4,9 +4,8 @@ ROOT="$(git rev-parse --show-toplevel)"
 cd "$ROOT"
 if git diff --cached --name-only | grep -qx "CLAUDE.md"; then
   tail -n +2 CLAUDE.md > /tmp/feishu-claude-body.$$
-  { echo "# feishu-user-plugin — Codex Instructions"; cat /tmp/feishu-claude-body.$$; } > AGENTS.md
+  { echo "# feishu-user-plugin — Codex 指令"; cat /tmp/feishu-claude-body.$$; } > AGENTS.md
   rm -f /tmp/feishu-claude-body.$$
-  cp CLAUDE.md skills/feishu-user-plugin/references/CLAUDE.md
-  git add AGENTS.md skills/feishu-user-plugin/references/CLAUDE.md
-  echo "[hook] CLAUDE.md → AGENTS.md + skill reference synced"
+  git add AGENTS.md
+  echo "[hook] CLAUDE.md → AGENTS.md synced"
 fi

package/scripts/verify-app-name.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// scripts/verify-app-name.js — diagnostic: does the current app have the
+// tenant-side `application:application:self_manage` scope?
+//
+// Hits Feishu's app-info endpoint with the current credentials' APP_ID/SECRET
+// and prints either the resolved app name (scope is granted) or the error
+// code (with remediation pointing at docs/AUTH-SETUP.md).
+//
+// Usage:
+//   node scripts/verify-app-name.js
+//
+// Exit codes:
+//   0  scope works, displayLabel will say "[Bot] AppName"
+//   1  99991672 — scope missing, displayLabel will fall back to "[Bot] (cli_xxx)"
+//   2  other auth failure (wrong APP_ID/SECRET, network, etc.)
+
+'use strict';
+
+const { readCredentials } = require('../src/auth/credentials');
+
+async function main() {
+  const creds = readCredentials() || {};
+  const appId = creds.LARK_APP_ID;
+  const appSecret = creds.LARK_APP_SECRET;
+  if (!appId || !appSecret) {
+    console.error('No LARK_APP_ID/SECRET in credentials. Run `npx feishu-user-plugin setup` first.');
+    process.exit(2);
+  }
+  console.error(`Probing app info for APP_ID=${appId}…`);
+
+  const tokenRes = await fetch('https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+  });
+  const tokenData = await tokenRes.json();
+  if (!tokenData.app_access_token) {
+    console.error(`app_access_token request failed: ${JSON.stringify(tokenData)}`);
+    process.exit(2);
+  }
+
+  const infoRes = await fetch(`https://open.feishu.cn/open-apis/application/v6/applications/${appId}?lang=zh_cn`, {
+    headers: { 'Authorization': `Bearer ${tokenData.app_access_token}` },
+  });
+  const info = await infoRes.json();
+
+  if (info.code === 0 && info.data?.app?.app_name) {
+    console.error(`OK — app name resolves to "${info.data.app.app_name}". displayLabel will read "[Bot] ${info.data.app.app_name}".`);
+    process.exit(0);
+  }
+  if (info.code === 99991672) {
+    console.error('FAIL — code 99991672. The tenant-side scope `application:application:self_manage` is not granted.');
+    console.error('Fix:');
+    console.error('  1. Open https://open.feishu.cn/app/<appId>/safe — "应用身份" tab');
+    console.error('  2. Add scope `application:application:self_manage` (marked 免审权限 — no admin review needed)');
+    console.error('  3. Save; no re-publish required');
+    console.error('  4. Re-run this script to confirm');
+    process.exit(1);
+  }
+  console.error(`FAIL — unexpected response: code=${info.code} msg=${info.msg || JSON.stringify(info)}`);
+  process.exit(2);
+}
+
+main().catch((e) => { console.error(`Threw: ${e.message}`); process.exit(2); });

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

@@ -1,8 +1,8 @@
 ---
 name: feishu-user-plugin
-version: "1.3.11"
-description: "All-in-one Feishu plugin — 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.8: multi-profile auto-switch on read errors (B), WebSocket realtime im.message events via get_new_events (C), credential pointer-only mode (E), CI gates (F), auth/uat.js + auth/cookie.js extracts (D)."
-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, 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
+version: "1.3.12"
+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.12: search_messages tool (Protobuf phase 2 B.5, UAT-only), CLI tool mode (`tool list` / `tool help <name>` / `tool <name> '<json>'`), IdentityState state machine + credentials hot-reload (no-restart UAT reload), displayLabel + sender semantics pack for LLM consumption, WS owner PID liveness check, gitleaks secret scan."
+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/search.md

@@ -15,8 +15,8 @@
    - `/digest 群名` 整理聊天摘要
 
 ## 通过邮箱或手机号查找
-如果用户提供了邮箱或手机号，改用 `find_user`：
+邮箱、手机号、姓名都可以作为 `query` 直接传给 `search_contacts`，不需要单独的工具：
 ```
-find_user({ email: "xxx@xxx.com" })
-find_user({ mobile: "+86xxx" })
+search_contacts({ query: "xxx@xxx.com" })
+search_contacts({ query: "+86xxx" })
 ```

package/src/auth/credentials-monitor.js

@@ -0,0 +1,185 @@
+// src/auth/credentials-monitor.js — single poller for credentials.json changes.
+//
+// The MCP server is long-lived; users routinely re-run `npx feishu-user-plugin
+// oauth` from another shell to refresh UAT, expecting the running server to
+// pick up the new token. Pre-v1.3.12 only the active-profile field was
+// observed (server.js::_syncActiveProfileFromDisk); UAT changes, cookie
+// rotations, and cache invalidation all required a Claude Code restart.
+//
+// CredentialsMonitor unifies the polling: per-tool-call `sync()` stats the
+// file, hashes its contents, and fires per-field hooks on diff. Owners
+// (officialClient, userClient, _userNameCache) register hooks at boot.
+//
+// Hash strategy: we don't trust mtime alone because `touch` would falsely
+// trigger a UAT reload across every dispatcher call. Content hash + mtime
+// means: skip the read entirely when mtime unchanged (cheap path), and
+// when mtime advanced compute SHA-256 of the active profile's fields and
+// compare per-field hashes to decide which hooks fire.
+//
+// Design choices:
+//   - factory not singleton: `createCredentialsMonitor({ path? })` so tests
+//     can use a tmpdir and server.js wires one against the real path.
+//   - synchronous sync(): callers are the request dispatcher; we can't await
+//     before handling a tool call. fs.statSync + fs.readFileSync are fine —
+//     credentials.json is tiny (a few KiB max).
+//   - hooks fire synchronously in registration order; exceptions are logged
+//     to stderr and don't block other hooks.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const DEFAULT_PATH = path.join(os.homedir(), '.feishu-user-plugin', 'credentials.json');
+
+function _hash(s) {
+  return crypto.createHash('sha256').update(s, 'utf8').digest('hex').slice(0, 16);
+}
+
+function _readSafely(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch (_) { return null; }
+}
+
+function _statSafely(p) {
+  try { return fs.statSync(p); } catch (_) { return null; }
+}
+
+function _parseSafely(s) {
+  try {
+    const o = JSON.parse(s);
+    if (o && typeof o === 'object' && o.profiles && o.active) return o;
+  } catch (_) {}
+  return null;
+}
+
+function _activeProfileEnv(canonical) {
+  if (!canonical) return null;
+  const p = canonical.profiles[canonical.active];
+  return p ? { ...p } : null;
+}
+
+function _fieldHash(env, key) {
+  if (!env || env[key] === undefined || env[key] === null) return null;
+  return _hash(String(env[key]));
+}
+
+function createCredentialsMonitor({ path: credPath = DEFAULT_PATH } = {}) {
+  const hooks = {
+    uat: [],
+    cookie: [],
+    profile: [],
+    invalidate: [],
+  };
+
+  // Baseline state: null until first successful sync().
+  let lastMtimeMs = null;
+  let lastActive = null;
+  let lastUatHash = null;
+  let lastCookieHash = null;
+  // refresh field is paired with UAT — refresh-only rotation also fires uat hook.
+  let lastRefreshHash = null;
+  // `_initialized` flips on first successful read. We DON'T reset on file
+  // disappearance — that way a user who briefly removes credentials.json
+  // (e.g. by hand-editing in vim with backup file shenanigans) doesn't see
+  // the next reappear treated as a silent rebaseline.
+  let _initialized = false;
+
+  function _fire(list, arg, label) {
+    for (const cb of list) {
+      try { cb(arg); } catch (e) {
+        console.error(`[feishu-user-plugin] credentials-monitor ${label} hook threw: ${e.message}`);
+      }
+    }
+  }
+
+  function sync() {
+    const stat = _statSafely(credPath);
+    if (!stat) {
+      // File missing — early return. We don't reset state because the file
+      // may reappear and we want to diff against what we last saw.
+      lastMtimeMs = null; // force re-read on reappear (mtime will differ)
+      return;
+    }
+    // Cheap exit when mtime hasn't advanced.
+    if (lastMtimeMs !== null && stat.mtimeMs === lastMtimeMs) return;
+
+    const raw = _readSafely(credPath);
+    if (raw === null) { lastMtimeMs = stat.mtimeMs; return; }
+    const canonical = _parseSafely(raw);
+    if (!canonical) { lastMtimeMs = stat.mtimeMs; return; }
+
+    const env = _activeProfileEnv(canonical);
+    const active = canonical.active;
+    const uatHash = _fieldHash(env, 'LARK_USER_ACCESS_TOKEN');
+    const cookieHash = _fieldHash(env, 'LARK_COOKIE');
+    const refreshHash = _fieldHash(env, 'LARK_USER_REFRESH_TOKEN');
+
+    // First observation establishes baseline silently.
+    const baselining = !_initialized;
+    lastMtimeMs = stat.mtimeMs;
+    _initialized = true;
+
+    if (baselining) {
+      lastActive = active;
+      lastUatHash = uatHash;
+      lastCookieHash = cookieHash;
+      lastRefreshHash = refreshHash;
+      return;
+    }
+
+    let anyChange = false;
+    if (active !== lastActive) {
+      anyChange = true;
+      const prev = lastActive;
+      lastActive = active;
+      _fire(hooks.profile, { from: prev, to: active, env }, 'profile');
+    }
+    if (uatHash !== lastUatHash || refreshHash !== lastRefreshHash) {
+      anyChange = true;
+      lastUatHash = uatHash;
+      lastRefreshHash = refreshHash;
+      _fire(hooks.uat, env, 'uat');
+    }
+    if (cookieHash !== lastCookieHash) {
+      anyChange = true;
+      lastCookieHash = cookieHash;
+      _fire(hooks.cookie, env, 'cookie');
+    }
+    if (anyChange) {
+      _fire(hooks.invalidate, env, 'invalidate');
+    }
+  }
+
+  // Force-fire all hooks as if everything changed. Used by switch_profile
+  // when it wants to short-circuit the mtime debounce.
+  function forceInvalidate() {
+    const stat = _statSafely(credPath);
+    const raw = stat ? _readSafely(credPath) : null;
+    const canonical = raw ? _parseSafely(raw) : null;
+    const env = _activeProfileEnv(canonical) || {};
+    _fire(hooks.profile, { from: lastActive, to: canonical?.active, env }, 'profile');
+    _fire(hooks.uat, env, 'uat');
+    _fire(hooks.cookie, env, 'cookie');
+    _fire(hooks.invalidate, env, 'invalidate');
+    if (canonical) {
+      lastActive = canonical.active;
+      lastUatHash = _fieldHash(env, 'LARK_USER_ACCESS_TOKEN');
+      lastCookieHash = _fieldHash(env, 'LARK_COOKIE');
+      lastRefreshHash = _fieldHash(env, 'LARK_USER_REFRESH_TOKEN');
+      lastMtimeMs = stat.mtimeMs;
+    }
+  }
+
+  return {
+    sync,
+    forceInvalidate,
+    onUatChange:    (cb) => { hooks.uat.push(cb); },
+    onCookieChange: (cb) => { hooks.cookie.push(cb); },
+    onProfileSwitch: (cb) => { hooks.profile.push(cb); },
+    onCacheInvalidate: (cb) => { hooks.invalidate.push(cb); },
+  };
+}
+
+module.exports = { createCredentialsMonitor };

package/src/auth/identity-state.js

@@ -0,0 +1,204 @@
+// src/auth/identity-state.js — identity state machine for UAT-first/bot-fallback flows.
+//
+// The v1.3.7 pattern was `asUserOrApp` in src/auth/uat.js: try UAT, catch any
+// failure, retry with bot, and attach a string `_fallbackWarning`. That works
+// but is opaque: the caller can't tell whether UAT was revoked (need to
+// re-oauth), expired (will refresh on next call), missing scope (need admin),
+// or just experienced a network blip. The 2026-05 incident showed how this
+// hides "UAT revoked for weeks" because every tool silently retried bot.
+//
+// This module adds a first-class IdentityState enum + a reactive cache. Each
+// call to withIdentityFallback returns `{ data, via, viaReason, identity }`;
+// LLMs and the get_login_status diagnostic can read the identity directly
+// instead of grepping warning strings.
+//
+// Cache: keyed by appId (one entry per LarkOfficialClient instance is enough
+// in practice — clients aren't shared across appIds in this codebase, but
+// keying by appId is the safe contract). 30 second TTL. Refined writes from
+// withIdentityFallback bypass TTL and write through immediately.
+//
+// What it owns:
+//   - IdentityState enum
+//   - resolveIdentity(client) — reads in-memory state into a state value
+//   - withIdentityFallback({client, uatFn, botFn, label}) — composable wrapper
+//   - invalidateIdentity(client) — cache eviction (CredentialsMonitor hook)
+
+'use strict';
+
+const IdentityState = Object.freeze({
+  VALID_USER:        'VALID_USER',
+  UAT_EXPIRED:       'UAT_EXPIRED',
+  UAT_REVOKED:       'UAT_REVOKED',
+  UAT_MISSING_SCOPE: 'UAT_MISSING_SCOPE',
+  BOT_ONLY:          'BOT_ONLY',
+  NO_CREDENTIALS:    'NO_CREDENTIALS',
+});
+
+const CACHE_TTL_MS = 30_000;
+const _cache = new Map(); // key = client.appId — value = { state, expiresAt }
+
+function _key(client) {
+  // Fall back to a sentinel for clients without appId so NO_CREDENTIALS is still cacheable.
+  return client?.appId || '__no_app__';
+}
+
+function _readInMemoryState(client) {
+  if (!client) return IdentityState.NO_CREDENTIALS;
+  const hasApp = !!client.appId;
+  const hasUAT = !!client.hasUAT;
+  if (!hasUAT && !hasApp) return IdentityState.NO_CREDENTIALS;
+  if (!hasUAT) return IdentityState.BOT_ONLY;
+  // hasUAT true — distinguish VALID_USER vs UAT_EXPIRED by expiry timestamp.
+  // expires=0 means "we never decoded — treat as valid and let the refresh
+  // path decide". Negative expiry never occurs but is treated as expired.
+  const now = Math.floor(Date.now() / 1000);
+  if (client._uatExpires && client._uatExpires > 0 && client._uatExpires <= now) {
+    return IdentityState.UAT_EXPIRED;
+  }
+  return IdentityState.VALID_USER;
+}
+
+async function resolveIdentity(client) {
+  const k = _key(client);
+  const cached = _cache.get(k);
+  if (cached && cached.expiresAt > Date.now()) return cached.state;
+  const state = _readInMemoryState(client);
+  _cache.set(k, { state, expiresAt: Date.now() + CACHE_TTL_MS });
+  return state;
+}
+
+function invalidateIdentity(client) {
+  _cache.delete(_key(client));
+}
+
+// Write a refined state through to the cache (bypasses TTL). Called when
+// withIdentityFallback observes a definitive UAT failure (revoked, missing
+// scope) — the cache should reflect what we just learned, not what was
+// inferred from in-memory state alone.
+function _refineIdentity(client, state) {
+  _cache.set(_key(client), { state, expiresAt: Date.now() + CACHE_TTL_MS });
+}
+
+// Classify a UAT-side failure into a refined IdentityState + a human-readable
+// via_reason string. Returns null if the failure isn't auth-related (caller
+// 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);
+    // 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}` };
+  }
+  if (!uatResp || typeof uatResp !== 'object') return null;
+  const code = uatResp.code;
+  const detail = `as user: code=${code} msg=${uatResp.msg}`;
+  switch (code) {
+    case 20064:    return { state: IdentityState.UAT_REVOKED,       viaReason: detail };
+    case 99991663: return { state: IdentityState.UAT_EXPIRED,       viaReason: detail };
+    case 99991668: return { state: IdentityState.UAT_MISSING_SCOPE, viaReason: detail };
+    case 99991677: return { state: IdentityState.UAT_EXPIRED,       viaReason: detail };
+    default:       return { state: null,                            viaReason: detail };
+  }
+}
+
+function _buildFallbackWarning({ identity, viaReason, hadUAT }) {
+  if (!hadUAT) {
+    // BOT_ONLY — the caller never configured UAT. Strictly speaking this
+    // isn't a "fallback" (no UAT attempt was made), but we keep the
+    // informational warning because users frequently *think* they configured
+    // UAT and are surprised to find resources owned by the shared bot. Same
+    // wording as the legacy asUserOrApp path so existing get_login_status
+    // expectations don't shift.
+    return `⚠️  未配置 UAT,本次操作以 bot 身份执行。资源归属于共享 bot「Claude聊天助手」,不是你。想让资源归你所有,先跑 \`npx feishu-user-plugin oauth\` 然后重启 Claude Code / Codex。`;
+  }
+  let hint;
+  switch (identity) {
+    case IdentityState.UAT_REVOKED:
+      hint = 'UAT 已被撤销 (invalid_grant)';
+      break;
+    case IdentityState.UAT_MISSING_SCOPE:
+      hint = 'UAT 缺少所需 scope';
+      break;
+    case IdentityState.UAT_EXPIRED:
+      hint = 'UAT 已过期';
+      break;
+    default:
+      hint = 'UAT 不可用';
+      break;
+  }
+  return `⚠️  ${hint} (${viaReason}),本次操作以 bot 身份执行。资源归属于共享 bot「Claude聊天助手」,不是你。恢复方法:运行 \`npx feishu-user-plugin oauth\` 后重启 Claude Code / Codex。`;
+}
+
+// withIdentityFallback({ client, uatFn, botFn, label })
+//
+// Tries uatFn first (when client has UAT), classifies any failure, then runs
+// botFn. Returns `{ data, via, viaReason?, identity, fallbackWarning? }`.
+// Throws an Error with `.uatSummary` and `.botError` when both sides fail.
+async function withIdentityFallback({ client, uatFn, botFn, label }) {
+  if (!label) throw new Error('withIdentityFallback: label is required (for error messages)');
+
+  let identity = await resolveIdentity(client);
+  const hadUAT = !!client?.hasUAT;
+  let uatSummary = null;
+
+  if (hadUAT) {
+    let uatResp = null;
+    let uatErr = null;
+    try {
+      uatResp = await uatFn();
+    } catch (e) {
+      uatErr = e;
+    }
+    if (uatResp && uatResp.code === 0) {
+      const data = { ...uatResp };
+      return { data, via: 'uat', identity };
+    }
+    const cls = _classifyUatFailure(uatResp, uatErr);
+    uatSummary = cls?.viaReason || `as user: unknown failure`;
+    if (cls?.state) {
+      identity = cls.state;
+      _refineIdentity(client, cls.state);
+    }
+    // fall through to bot
+  }
+
+  // Bot path
+  let botData;
+  let botError;
+  try {
+    botData = await botFn();
+  } catch (e) {
+    botError = e;
+  }
+
+  if (botError) {
+    if (uatSummary) {
+      const err = new Error(`${label} failed on both identities. ${uatSummary}. as app: ${botError.message}`);
+      err.uatSummary = uatSummary;
+      err.botError = botError;
+      err.identity = identity;
+      throw err;
+    }
+    throw botError;
+  }
+
+  // Decorate the bot response with via metadata + (when UAT was attempted) a
+  // fallback warning the caller can surface to the LLM.
+  const data = { ...botData };
+  data._viaUser = false;
+  const fallbackWarning = _buildFallbackWarning({ identity, viaReason: uatSummary, hadUAT });
+  if (fallbackWarning) data._fallbackWarning = fallbackWarning;
+  const out = { data, via: 'bot', identity };
+  if (uatSummary) out.viaReason = uatSummary;
+  if (fallbackWarning) out.fallbackWarning = fallbackWarning;
+  return out;
+}
+
+module.exports = {
+  IdentityState,
+  resolveIdentity,
+  withIdentityFallback,
+  invalidateIdentity,
+  _refineIdentity, // exported for D's CredentialsMonitor hook (private API)
+  _readInMemoryState, // exported for testing edge cases (private API)
+};

package/src/auth/uat.js

@@ -9,9 +9,16 @@
 //   - decodeTokenExpiry(token) — JWT exp parsing
 //   - getValidUAT(client) — returns current UAT, refreshes if expiring
 //   - refreshUAT(client) — full refresh dance with file lock + persist
-//   - withUAT(client, fn) — wrapper that retries fn once on auth-error codes
+//   - withUAT(client, fn) — wrapper that retries fn once on auth codes + on
+//     transient throws (classifyError action='retry'); v1.3.12 widening
 //   - uatREST(client, method, path, opts) — generic UAT REST helper
-//   - asUserOrApp(client, opts) — UAT-first, bot-fallback wrapper
+//   - asUserOrApp(client, opts) — legacy UAT-first / bot-fallback signature.
+//     v1.3.12: the body is now a thin shape adapter around
+//     withIdentityFallback (src/auth/identity-state.js). The public contract
+//     — return data with _viaUser ∈ {true,false} + optional _fallbackWarning,
+//     throw Error with .uatSummary + .appError on dual failure — is
+//     preserved so 15+ existing callsites in calendar/docs/bitable/wiki/okr/
+//     tasks/drive/im keep compiling.
 //   - persistUAT(client) — writes through auth/credentials
 //   - adoptPersistedUATIfNewer(client) — peer-rotation adoption
 //   - acquireRefreshLock / releaseRefreshLock — cross-process advisory lock
@@ -144,8 +151,24 @@ function persistUAT(client) {
 }
 
 async function withUAT(client, fn) {
+  const { classifyError } = require('../error-codes');
   let uat = await getValidUAT(client);
-  const data = await fn(uat);
+
+  // First attempt. If fn() throws an upstream flake (network reset, response
+  // body truncated mid-JSON, gateway 5xx), classifyError says action='retry'
+  // and we re-run once with the same UAT — the token is still valid, the
+  // call just lost. Auth-related codes are the existing refresh path below.
+  let data;
+  try {
+    data = await fn(uat);
+  } catch (err) {
+    const cls = classifyError(err);
+    if (cls.action === 'retry') {
+      return fn(uat);
+    }
+    throw err;
+  }
+
   if (data.code === 99991668 || data.code === 99991663 || data.code === 99991677) {
     if (data.code === 99991668 && typeof data.msg === 'string' && /not support/i.test(data.msg)) {
       return data;
@@ -182,40 +205,31 @@ async function uatREST(client, method, urlPath, { body, query } = {}) {
 }
 
 async function asUserOrApp(client, { uatPath, method = 'GET', body, query, sdkFn, label }) {
-  let uatSummary = null;
-  if (client.hasUAT) {
-    try {
-      const data = await uatREST(client, method, uatPath, { body, query });
-      if (data.code === 0) {
-        data._viaUser = true;
-        return data;
-      }
-      uatSummary = `as user: code=${data.code} msg=${data.msg}`;
-      console.error(`[feishu-user-plugin] ${label} ${uatSummary}, retrying as app`);
-    } catch (err) {
-      uatSummary = `as user: ${err.message}`;
-      console.error(`[feishu-user-plugin] ${label} as user threw (${err.message}), retrying as app`);
-    }
-  }
+  // v1.3.12: internal implementation routes through withIdentityFallback in
+  // src/auth/identity-state.js. The public shape — return data with _viaUser
+  // and optional _fallbackWarning, throw Error with .uatSummary + .appError
+  // when both sides fail — is preserved for 15+ existing callsites.
+  const { withIdentityFallback } = require('./identity-state');
   try {
-    const appData = await client._safeSDKCall(sdkFn, label);
-    if (appData && typeof appData === 'object') {
-      appData._viaUser = false;
-      if (uatSummary) {
-        appData._fallbackWarning = `⚠️  UAT 不可用 (${uatSummary}),本次操作以 bot 身份执行。资源归属于共享 bot「Claude聊天助手」,不是你。恢复方法:运行 \`npx feishu-user-plugin oauth\` 后重启 Claude Code / Codex。`;
-      } else if (!client.hasUAT) {
-        appData._fallbackWarning = `⚠️  未配置 UAT,本次操作以 bot 身份执行。资源归属于共享 bot「Claude聊天助手」,不是你。想让资源归你所有,先跑 \`npx feishu-user-plugin oauth\` 然后重启 Claude Code / Codex。`;
-      }
-    }
-    return appData;
-  } catch (appErr) {
-    if (uatSummary) {
-      const err = new Error(`${label} failed on both identities. ${uatSummary}. as app: ${appErr.message}`);
-      err.uatSummary = uatSummary;
-      err.appError = appErr;
-      throw err;
+    const result = await withIdentityFallback({
+      client,
+      uatFn: () => uatREST(client, method, uatPath, { body, query }),
+      botFn: () => client._safeSDKCall(sdkFn, label),
+      label,
+    });
+    // Surface state machine breadcrumbs in stderr so long-running servers can
+    // be diagnosed without grepping the LLM transcript. (Pre-v1.3.12 already
+    // logged on fallback; we keep parity but only when fallback actually
+    // happened, not on every BOT_ONLY call.)
+    if (result.via === 'bot' && result.viaReason) {
+      console.error(`[feishu-user-plugin] ${label} fell back to bot (${result.identity}): ${result.viaReason}`);
     }
-    throw appErr;
+    return result.data;
+  } catch (e) {
+    // Legacy callers expect err.appError — keep the alias alongside the new
+    // err.botError that withIdentityFallback sets.
+    if (e && e.botError && !e.appError) e.appError = e.botError;
+    throw e;
   }
 }