feishu-user-plugin 1.0.1 → 1.1.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.0.0",
-  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself, read chats, manage docs/tables/wiki. 33 tools + 8 skills, 3 auth layers.",
+  "version": "1.1.0",
+  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself, read chats, manage docs/tables/wiki. 33 tools + 9 skills, 3 auth layers.",
   "author": {
     "name": "EthanQC"
   },

package/CHANGELOG.md

@@ -4,6 +4,58 @@ 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.1.0] - 2026-03-11
+
+### Fixed
+- **read_messages 400 error hidden**: Now shows actual Feishu error code and description instead of just "Request failed with status code 400"
+- **Messages returned oldest first**: Default sort is now `ByCreateTimeDesc` (newest messages first) for both `read_messages` and `read_p2p_messages`
+- **Chat name resolution**: Added `im.v1.chat.search` API as fallback when bot's group list doesn't contain the target chat
+- **get_user_info fails for external users**: Added official contact API fallback (`contact.user.get`) for cross-tenant user lookup
+- **Messages lack sender names**: `read_messages` and `read_p2p_messages` now auto-resolve sender IDs to display names
+- **UAT persistence writes to npx temp dir**: Now persists refreshed tokens to `~/.claude.json` MCP config instead
+- **oauth-auto.js missing offline_access scope**: Added `offline_access` to SCOPES (was missing, causing no refresh_token)
+- **README "8 slash commands"**: Corrected to "9 slash commands" (was missing /drive)
+- **CLAUDE.md false "type: stdio" warning**: Removed — `"type": "stdio"` is standard and harmless in Claude Code
+
+### Added
+- `sort_type` parameter for `read_messages` and `read_p2p_messages` (`ByCreateTimeDesc` / `ByCreateTimeAsc`)
+- `senderName` field in message results (auto-resolved from sender ID)
+- CLI subcommands: `npx feishu-user-plugin setup` (wizard), `oauth`, `status`
+- `src/cli.js` — CLI dispatcher for subcommands
+- `src/setup.js` — Interactive setup wizard (writes MCP config, validates credentials)
+- `chatSearch()` method in official client (uses `im.v1.chat.search`)
+- `getUserById()` method with caching for user name resolution
+- `_safeSDKCall()` wrapper that extracts real Feishu errors from Lark SDK AxiosErrors
+- `_populateSenderNames()` for batch sender name resolution in message lists
+
+### Changed
+- `package.json` bin entry points to `src/cli.js` (supports subcommands, default still starts MCP server)
+- team-skills README rewritten for pure npm flow (no clone needed)
+- CLAUDE.md OAuth instructions updated to use `npx feishu-user-plugin oauth`
+- Error messages across all 33 tools now include actual Feishu error codes
+
+## [1.0.2] - 2026-03-10
+
+### Fixed
+- `list_user_chats` description incorrectly claimed "including P2P" — actually only returns groups
+- OAuth scope `contact:user.id:readonly` → `contact:user.base:readonly` in README
+- Cookie length validation range (500-5000, was 1000-5000)
+- Version inconsistency across `server.json`, `plugin.json`, `SKILL.md`, `src/index.js`
+- Skill count: 8 → 9 (was missing `/drive`)
+- README_CN.md Claude Desktop config missing `env` block
+
+### Added
+- Startup auth diagnostics in `src/index.js` (Cookie/App/UAT status logging)
+- `LARK_USER_REFRESH_TOKEN` to all MCP config examples
+- Troubleshooting for `invalid_grant` errors (28003/20003/20005)
+- Troubleshooting for `oauth.js` requiring APP_ID/SECRET in `.env`
+- Playwright cookie setup: two-step extraction, `clearCookies()`, ASCII validation
+- `LARK_USER_REFRESH_TOKEN` to `server.json` environment_variables
+
+### Changed
+- All 5 env vars marked as required for full functionality
+- Improved `read_p2p_messages` chat_id description (numeric + oc_xxx both accepted)
+
 ## [1.0.0] - 2026-03-09
 
 ### Changed

package/README.md

@@ -6,7 +6,7 @@
 [![Tools](https://img.shields.io/badge/Tools-33-orange.svg)](#tools-33-total)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-**All-in-one Feishu/Lark MCP Server -- 33 tools, 8 skills, 3 auth layers for messaging, docs, tables, wiki, and drive.**
+**All-in-one Feishu/Lark MCP Server -- 33 tools, 9 skills, 3 auth layers for messaging, docs, tables, wiki, and drive.**
 
 The only MCP server that lets you send messages as your **personal identity** (not a bot), while also integrating the full official Feishu API for documents, spreadsheets, wikis, and more.
 
@@ -16,7 +16,7 @@ The only MCP server that lets you send messages as your **personal identity** (n
 - **Read everything** -- Group chats via bot API, P2P (direct messages) via OAuth UAT.
 - **Full Feishu suite** -- Docs, Bitable (spreadsheets), Wiki, Drive, Contacts -- all in one plugin.
 - **3 auth layers** -- Cookie-based user identity, app credentials (Official API), and OAuth UAT (P2P reading). All three are needed for full functionality.
-- **8 slash commands** for Claude Code -- `/send`, `/reply`, `/search`, `/digest`, `/doc`, `/table`, `/wiki`, `/status`
+- **9 slash commands** for Claude Code -- `/send`, `/reply`, `/search`, `/digest`, `/doc`, `/table`, `/wiki`, `/drive`, `/status`
 - **Auto session management** -- Cookie heartbeat every 4h, UAT auto-refresh with token rotation.
 - **Chat name resolution** -- Pass a group name instead of `oc_xxx` ID; it resolves automatically.
 
@@ -82,7 +82,7 @@ Go to **Permissions & Scopes** (权限管理) and add the following scopes:
 | `bitable:record` | Read and write Bitable records |
 | `wiki:wiki:readonly` | Read wiki spaces and nodes |
 | `drive:drive:readonly` | List Drive files and folders |
-| `contact:user.id:readonly` | Look up users by email/mobile |
+| `contact:user.base:readonly` | Look up users by email/mobile |
 
 > Add more scopes as needed depending on which tools you use.
 
@@ -338,7 +338,7 @@ Send messages as yourself, not as a bot.
 | Tool | Description |
 |------|-------------|
 | `read_p2p_messages` | Read P2P (direct message) history. Works for chats the bot cannot access. |
-| `list_user_chats` | List all chats the user is in, including P2P. |
+| `list_user_chats` | List group chats the user is in. Note: only returns groups, not P2P. |
 
 ### Official API -- IM (Bot Identity)
 
@@ -388,9 +388,9 @@ Send messages as yourself, not as a bot.
 |------|-------------|
 | `find_user` | Find user by email or mobile number |
 
-## Claude Code Slash Commands (8 skills)
+## Claude Code Slash Commands (9 skills)
 
-This plugin includes 8 built-in skills in `skills/feishu-user-plugin/`:
+This plugin includes 9 built-in skills in `skills/feishu-user-plugin/`:
 
 | Skill | Usage | Description |
 |-------|-------|-------------|
@@ -401,6 +401,7 @@ This plugin includes 8 built-in skills in `skills/feishu-user-plugin/`:
 | `/doc` | `/doc search MCP` | Search, read, or create documents |
 | `/table` | `/table query appXxx` | Query or create Bitable records |
 | `/wiki` | `/wiki search protocol` | Search and browse wiki |
+| `/drive` | `/drive list folderToken` | List files or create folders in Drive |
 | `/status` | `/status` | Check login and auth status |
 
 Skills are automatically available when the plugin is installed.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.0.1",
-  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself, read chats, manage docs/tables/wiki. 33 tools + 8 skills, 3 auth layers.",
+  "version": "1.1.0",
+  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself, read chats, manage docs/tables/wiki. 33 tools + 9 skills, 3 auth layers.",
   "main": "src/index.js",
   "bin": {
-    "feishu-user-plugin": "src/index.js"
+    "feishu-user-plugin": "src/cli.js"
   },
   "scripts": {
     "start": "node src/index.js",

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

@@ -1,6 +1,6 @@
 ---
 name: feishu-user-plugin
-version: "1.0.0"
+version: "1.1.0"
 description: "All-in-one Feishu plugin — send messages as yourself, read group/P2P chats, manage docs/tables/wiki. Replaces and extends the official Feishu MCP."
 allowed-tools: send_to_user, send_to_group, send_as_user, send_image_as_user, send_file_as_user, send_post_as_user, send_sticker_as_user, send_audio_as_user, search_contacts, create_p2p_chat, get_chat_info, get_user_info, get_login_status, read_p2p_messages, list_user_chats, list_chats, read_messages, reply_message, forward_message, search_docs, read_doc, create_doc, list_bitable_tables, list_bitable_fields, search_bitable_records, create_bitable_record, update_bitable_record, list_wiki_spaces, search_wiki, list_wiki_nodes, list_files, create_folder, find_user
 user_invocable: true

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

@@ -93,7 +93,7 @@ window.__COOKIE__
 
 **Step 4: Validate** — Must be pure ASCII, contain `session=` and `sl_session=`, length 500-5000. If >10000, it's contaminated.
 
-**Step 5: Write config** using exact format (NO `"type": "stdio"`):
+**Step 5: Write config** using exact format:
 ```json
 {
   "feishu-user-plugin": {

package/src/cli.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for feishu-user-plugin
+ *
+ * Usage:
+ *   npx feishu-user-plugin          → Start MCP server (default, used by Claude Code)
+ *   npx feishu-user-plugin setup    → Interactive setup wizard
+ *   npx feishu-user-plugin oauth    → Run OAuth flow for UAT
+ *   npx feishu-user-plugin status   → Check auth status
+ */
+
+const cmd = process.argv[2];
+
+switch (cmd) {
+  case 'setup':
+    require('./setup');
+    break;
+  case 'oauth':
+    require('./oauth');
+    break;
+  case 'status':
+    checkStatus();
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+    printHelp();
+    break;
+  default:
+    // Default: start MCP server (used by Claude Code / MCP clients)
+    require('./index');
+    break;
+}
+
+function printHelp() {
+  console.log(`
+feishu-user-plugin — All-in-one Feishu MCP Server
+
+Commands:
+  (default)   Start MCP server (used by Claude Code)
+  setup       Interactive setup wizard — writes MCP config
+  oauth       Run OAuth flow to obtain user_access_token
+  status      Check authentication status
+  help        Show this help
+
+Quick Start (team members):
+  1. npx feishu-user-plugin setup
+  2. Follow the prompts to configure credentials
+  3. Restart Claude Code
+
+Quick Start (external users):
+  1. Create a Feishu app at https://open.feishu.cn/app
+  2. npx feishu-user-plugin setup
+  3. npx feishu-user-plugin oauth
+  4. Restart Claude Code
+`);
+}
+
+async function checkStatus() {
+  const { LarkUserClient } = require('./client');
+  const { LarkOfficialClient } = require('./official');
+  const path = require('path');
+  require('dotenv').config({ path: path.join(__dirname, '..', '.env') });
+
+  console.log('=== feishu-user-plugin Auth Status ===\n');
+
+  // Cookie
+  const cookie = process.env.LARK_COOKIE;
+  if (cookie) {
+    try {
+      const client = new LarkUserClient(cookie);
+      await client.init();
+      console.log(`Cookie: OK (user: ${client.userName || client.userId})`);
+    } catch (e) {
+      console.log(`Cookie: FAILED — ${e.message}`);
+    }
+  } else {
+    console.log('Cookie: NOT SET');
+  }
+
+  // App credentials
+  const appId = process.env.LARK_APP_ID;
+  const appSecret = process.env.LARK_APP_SECRET;
+  console.log(`App credentials: ${appId && appSecret ? 'OK' : 'NOT SET'}`);
+
+  // UAT
+  const uat = process.env.LARK_USER_ACCESS_TOKEN;
+  const rt = process.env.LARK_USER_REFRESH_TOKEN;
+  if (uat) {
+    console.log(`UAT: SET (refresh_token: ${rt ? 'YES' : 'NO'})`);
+    if (appId && appSecret) {
+      const official = new LarkOfficialClient(appId, appSecret);
+      official.loadUAT();
+      try {
+        const chats = await official.listChatsAsUser({ pageSize: 1 });
+        console.log(`  UAT test: OK (can list chats)`);
+      } catch (e) {
+        console.log(`  UAT test: FAILED — ${e.message}`);
+      }
+    }
+  } else {
+    console.log('UAT: NOT SET (run: npx feishu-user-plugin oauth)');
+  }
+}

package/src/index.js

@@ -48,8 +48,24 @@ class ChatIdMapper {
 
   async resolveToOcId(chatIdOrName, official) {
     if (chatIdOrName.startsWith('oc_')) return chatIdOrName;
-    // Try as chat name
-    return this.findByName(chatIdOrName, official);
+    // Strategy 1: Search in bot's group list cache
+    const cached = await this.findByName(chatIdOrName, official);
+    if (cached) return cached;
+    // Strategy 2: Use im.v1.chat.search API (finds groups even if not in cache)
+    try {
+      const results = await official.chatSearch(chatIdOrName);
+      for (const chat of results) {
+        this.nameCache.set(chat.chat_id, chat.name || '');
+        if (chat.name === chatIdOrName) return chat.chat_id;
+      }
+      // Partial match on search results
+      for (const chat of results) {
+        if (chat.name && chat.name.includes(chatIdOrName)) return chat.chat_id;
+      }
+    } catch (e) {
+      console.error('[feishu-user-plugin] chatSearch fallback failed:', e.message);
+    }
+    return null;
   }
 }
 
@@ -251,7 +267,7 @@ const TOOLS = [
   // ========== IM — Official API (User Identity via UAT) ==========
   {
     name: 'read_p2p_messages',
-    description: '[User UAT] Read P2P (direct message) chat history using user_access_token. Works for chats the bot cannot access. Requires OAuth setup: run "node src/oauth.js" first.',
+    description: '[User UAT] Read P2P (direct message) chat history using user_access_token. Works for chats the bot cannot access. Returns newest messages first by default. Requires OAuth setup.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -259,6 +275,7 @@ const TOOLS = [
         page_size: { type: 'number', description: 'Messages to fetch (default 20, max 50)' },
         start_time: { type: 'string', description: 'Start timestamp in seconds (optional)' },
         end_time: { type: 'string', description: 'End timestamp in seconds (optional)' },
+        sort_type: { type: 'string', enum: ['ByCreateTimeDesc', 'ByCreateTimeAsc'], description: 'Sort order (default: ByCreateTimeDesc = newest first)' },
       },
       required: ['chat_id'],
     },
@@ -289,7 +306,7 @@ const TOOLS = [
   },
   {
     name: 'read_messages',
-    description: '[Official API] Read message history. Accepts oc_xxx ID or chat name (auto-resolved).',
+    description: '[Official API] Read message history. Accepts oc_xxx ID or chat name (auto-searched via bot group list + im.chat.search). Returns newest messages first by default, with sender names resolved.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -297,6 +314,7 @@ const TOOLS = [
         page_size: { type: 'number', description: 'Messages to fetch (default 20, max 50)' },
         start_time: { type: 'string', description: 'Start timestamp in seconds (optional)' },
         end_time: { type: 'string', description: 'End timestamp in seconds (optional)' },
+        sort_type: { type: 'string', enum: ['ByCreateTimeDesc', 'ByCreateTimeAsc'], description: 'Sort order (default: ByCreateTimeDesc = newest first)' },
       },
       required: ['chat_id'],
     },
@@ -490,7 +508,7 @@ const TOOLS = [
 // --- Server ---
 
 const server = new Server(
-  { name: 'feishu-user-plugin', version: '1.0.0' },
+  { name: 'feishu-user-plugin', version: '1.1.0' },
   { capabilities: { tools: {} } }
 );
 
@@ -583,15 +601,24 @@ async function handleTool(name, args) {
       return info ? json(info) : text(`No info for chat ${args.chat_id}`);
     }
     case 'get_user_info': {
-      const c = await getUserClient();
-      // Try name cache first; if miss, do a search to populate cache
-      let n = await c.getUserName(args.user_id);
-      if (!n && args.user_id) {
-        // Try searching to populate the cache
-        await c.search(args.user_id);
+      let n = null;
+      // Strategy 1: User identity client cache
+      try {
+        const c = await getUserClient();
         n = await c.getUserName(args.user_id);
+        if (!n && args.user_id) {
+          await c.search(args.user_id);
+          n = await c.getUserName(args.user_id);
+        }
+      } catch {}
+      // Strategy 2: Official API contact lookup (works for same-tenant users)
+      if (!n) {
+        try {
+          const official = getOfficialClient();
+          n = await official.getUserById(args.user_id, 'open_id');
+        } catch {}
       }
-      return text(n ? `User ${args.user_id}: ${n}` : `Could not resolve user ${args.user_id}. Try search_contacts with the user's name instead.`);
+      return text(n ? `User ${args.user_id}: ${n}` : `Could not resolve user ${args.user_id}. This user may be from an external tenant. Try search_contacts with the user's display name instead.`);
     }
     case 'get_login_status': {
       const parts = [];
@@ -614,6 +641,7 @@ async function handleTool(name, args) {
       const official = getOfficialClient();
       return json(await official.readMessagesAsUser(args.chat_id, {
         pageSize: args.page_size, startTime: args.start_time, endTime: args.end_time,
+        sortType: args.sort_type,
       }));
     }
     case 'list_user_chats':
@@ -627,10 +655,11 @@ async function handleTool(name, args) {
       const official = getOfficialClient();
       const resolvedChatId = await chatIdMapper.resolveToOcId(args.chat_id, official);
       if (!resolvedChatId) {
-        return text(`Cannot resolve "${args.chat_id}" to oc_ ID. Use list_chats to find the correct ID, or provide chat name.`);
+        return text(`Cannot resolve "${args.chat_id}" to oc_ ID. Searched bot's group list and used im.chat.search API — no match found.\nTry: list_chats to see all bot groups, or provide the oc_xxx ID directly.\nIf the bot is not in this group, use read_p2p_messages with UAT instead.`);
       }
       return json(await official.readMessages(resolvedChatId, {
         pageSize: args.page_size, startTime: args.start_time, endTime: args.end_time,
+        sortType: args.sort_type,
       }));
     }
     case 'reply_message':
@@ -696,7 +725,7 @@ async function main() {
   const hasCookie = !!process.env.LARK_COOKIE;
   const hasApp = !!(process.env.LARK_APP_ID && process.env.LARK_APP_SECRET);
   const hasUAT = !!process.env.LARK_USER_ACCESS_TOKEN;
-  console.error(`[feishu-user-plugin] MCP Server v1.0.1 — ${TOOLS.length} tools`);
+  console.error(`[feishu-user-plugin] MCP Server v1.1.0 — ${TOOLS.length} tools`);
   console.error(`[feishu-user-plugin] Auth: Cookie=${hasCookie ? 'YES' : 'NO'} App=${hasApp ? 'YES' : 'NO'} UAT=${hasUAT ? 'YES' : 'NO'}`);
   if (!hasCookie) console.error('[feishu-user-plugin] WARNING: LARK_COOKIE not set — user identity tools (send_to_user, etc.) will fail');
   if (!hasApp) console.error('[feishu-user-plugin] WARNING: LARK_APP_ID/SECRET not set — official API tools (read_messages, docs, etc.) will fail');

package/src/oauth-auto.js

@@ -13,7 +13,7 @@ const APP_SECRET = process.env.LARK_APP_SECRET;
 const COOKIE_STR = process.env.LARK_COOKIE;
 const PORT = 9997;
 const REDIRECT_URI = `http://127.0.0.1:${PORT}/callback`;
-const SCOPES = 'im:message im:message:readonly im:chat:readonly contact:user.base:readonly';
+const SCOPES = 'offline_access im:message im:message:readonly im:chat:readonly contact:user.base:readonly';
 
 function parseCookies(cookieStr) {
   return cookieStr.split(';').map(c => {

package/src/official.js

@@ -8,6 +8,7 @@ class LarkOfficialClient {
     this._uat = null;
     this._uatRefresh = null;
     this._uatExpires = 0;
+    this._userNameCache = new Map(); // open_id → display name
   }
 
   // --- UAT (User Access Token) Management ---
@@ -66,14 +67,60 @@ class LarkOfficialClient {
   _persistUAT() {
     const fs = require('fs');
     const path = require('path');
+    const updates = {
+      LARK_USER_ACCESS_TOKEN: this._uat,
+      LARK_USER_REFRESH_TOKEN: this._uatRefresh,
+      LARK_UAT_EXPIRES: String(this._uatExpires),
+    };
+
+    // Strategy 1: Update ~/.claude.json MCP config (works for npx users)
+    const claudeJsonPaths = [
+      path.join(process.env.HOME || '', '.claude.json'),
+      path.join(process.env.HOME || '', '.claude', '.claude.json'),
+    ];
+    for (const cjPath of claudeJsonPaths) {
+      try {
+        const raw = fs.readFileSync(cjPath, 'utf8');
+        const config = JSON.parse(raw);
+        const servers = config.mcpServers || {};
+        // Find our server entry by name
+        for (const name of ['feishu-user-plugin', 'feishu']) {
+          if (servers[name]?.env) {
+            Object.assign(servers[name].env, updates);
+            fs.writeFileSync(cjPath, JSON.stringify(config, null, 2) + '\n');
+            console.error('[feishu-user-plugin] UAT persisted to', cjPath);
+            return;
+          }
+        }
+      } catch {}
+    }
+
+    // Strategy 2: Update project .mcp.json
+    const mcpJsonPaths = [
+      path.join(process.cwd(), '.mcp.json'),
+    ];
+    for (const mjPath of mcpJsonPaths) {
+      try {
+        const raw = fs.readFileSync(mjPath, 'utf8');
+        const config = JSON.parse(raw);
+        const servers = config.mcpServers || config;
+        for (const name of ['feishu-user-plugin', 'feishu']) {
+          if (servers[name]?.env) {
+            Object.assign(servers[name].env, updates);
+            fs.writeFileSync(mjPath, JSON.stringify(config, null, 2) + '\n');
+            console.error('[feishu-user-plugin] UAT persisted to', mjPath);
+            return;
+          }
+        }
+      } catch {}
+    }
+
+    // Strategy 3: Fallback to .env in project root (for local dev)
     const envPath = path.join(__dirname, '..', '.env');
     try {
-      let env = fs.readFileSync(envPath, 'utf8');
-      for (const [key, val] of Object.entries({
-        LARK_USER_ACCESS_TOKEN: this._uat,
-        LARK_USER_REFRESH_TOKEN: this._uatRefresh,
-        LARK_UAT_EXPIRES: String(this._uatExpires),
-      })) {
+      let env = '';
+      try { env = fs.readFileSync(envPath, 'utf8'); } catch {}
+      for (const [key, val] of Object.entries(updates)) {
         const regex = new RegExp(`^${key}=.*$`, 'm');
         if (regex.test(env)) env = env.replace(regex, `${key}=${val}`);
         else env += `\n${key}=${val}`;
@@ -109,9 +156,10 @@ class LarkOfficialClient {
     return { items: data.data.items || [], pageToken: data.data.page_token, hasMore: data.data.has_more };
   }
 
-  async readMessagesAsUser(chatId, { pageSize = 20, startTime, endTime, pageToken } = {}) {
+  async readMessagesAsUser(chatId, { pageSize = 20, startTime, endTime, pageToken, sortType = 'ByCreateTimeDesc' } = {}) {
     const params = new URLSearchParams({
       container_id_type: 'chat', container_id: chatId, page_size: String(pageSize),
+      sort_type: sortType,
     });
     if (startTime) params.set('start_time', startTime);
     if (endTime) params.set('end_time', endTime);
@@ -123,98 +171,107 @@ class LarkOfficialClient {
       return res.json();
     });
     if (data.code !== 0) throw new Error(`readMessagesAsUser failed (${data.code}): ${data.msg}`);
-    return {
-      items: (data.data.items || []).map(m => this._formatMessage(m)),
-      hasMore: data.data.has_more,
-      pageToken: data.data.page_token,
-    };
+    const items = (data.data.items || []).map(m => this._formatMessage(m));
+    await this._populateSenderNames(items);
+    return { items, hasMore: data.data.has_more, pageToken: data.data.page_token };
   }
 
   // --- IM ---
 
   async listChats({ pageSize = 20, pageToken } = {}) {
-    const res = await this.client.im.chat.list({ params: { page_size: pageSize, page_token: pageToken } });
-    if (res.code !== 0) throw new Error(`listChats failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(
+      () => this.client.im.chat.list({ params: { page_size: pageSize, page_token: pageToken } }),
+      'listChats'
+    );
     return { items: res.data.items || [], pageToken: res.data.page_token, hasMore: res.data.has_more };
   }
 
-  async readMessages(chatId, { pageSize = 20, startTime, endTime, pageToken } = {}) {
-    const params = { container_id_type: 'chat', container_id: chatId, page_size: pageSize };
+  async readMessages(chatId, { pageSize = 20, startTime, endTime, pageToken, sortType = 'ByCreateTimeDesc' } = {}) {
+    const params = { container_id_type: 'chat', container_id: chatId, page_size: pageSize, sort_type: sortType };
     if (startTime) params.start_time = startTime;
     if (endTime) params.end_time = endTime;
     if (pageToken) params.page_token = pageToken;
-    const res = await this.client.im.message.list({ params });
-    if (res.code !== 0) throw new Error(`readMessages failed (${res.code}): ${res.msg}`);
-    return { items: (res.data.items || []).map(m => this._formatMessage(m)), hasMore: res.data.has_more, pageToken: res.data.page_token };
+    const res = await this._safeSDKCall(() => this.client.im.message.list({ params }), 'readMessages');
+    const items = (res.data.items || []).map(m => this._formatMessage(m));
+    await this._populateSenderNames(items);
+    return { items, hasMore: res.data.has_more, pageToken: res.data.page_token };
   }
 
   async getMessage(messageId) {
-    const res = await this.client.im.message.get({ path: { message_id: messageId } });
-    if (res.code !== 0) throw new Error(`getMessage failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(
+      () => this.client.im.message.get({ path: { message_id: messageId } }),
+      'getMessage'
+    );
     return this._formatMessage(res.data);
   }
 
   async replyMessage(messageId, text, msgType = 'text') {
     const content = msgType === 'text' ? JSON.stringify({ text }) : text;
-    const res = await this.client.im.message.reply({
-      path: { message_id: messageId },
-      data: { content, msg_type: msgType },
-    });
-    if (res.code !== 0) throw new Error(`replyMessage failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(
+      () => this.client.im.message.reply({ path: { message_id: messageId }, data: { content, msg_type: msgType } }),
+      'replyMessage'
+    );
     return { messageId: res.data.message_id };
   }
 
   async forwardMessage(messageId, receiverId, receiveIdType = 'chat_id') {
-    const res = await this.client.im.message.forward({
-      path: { message_id: messageId },
-      data: { receive_id: receiverId },
-      params: { receive_id_type: receiveIdType },
-    });
-    if (res.code !== 0) throw new Error(`forwardMessage failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(
+      () => this.client.im.message.forward({
+        path: { message_id: messageId },
+        data: { receive_id: receiverId },
+        params: { receive_id_type: receiveIdType },
+      }),
+      'forwardMessage'
+    );
     return { messageId: res.data.message_id };
   }
 
   // --- Docs ---
 
   async searchDocs(query, { pageSize = 10, pageToken } = {}) {
-    const res = await this.client.request({
-      method: 'POST',
-      url: '/open-apis/suite/docs-api/search/object',
-      data: { search_key: query, count: pageSize, offset: pageToken ? parseInt(pageToken) : 0, owner_ids: [], chat_ids: [], docs_types: [] },
-    });
-    if (res.code !== 0) throw new Error(`searchDocs failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(
+      () => this.client.request({
+        method: 'POST', url: '/open-apis/suite/docs-api/search/object',
+        data: { search_key: query, count: pageSize, offset: pageToken ? parseInt(pageToken) : 0, owner_ids: [], chat_ids: [], docs_types: [] },
+      }),
+      'searchDocs'
+    );
     return { items: res.data.docs_entities || [], hasMore: res.data.has_more };
   }
 
   async readDoc(documentId) {
-    const res = await this.client.docx.document.rawContent({ path: { document_id: documentId }, params: { lang: 0 } });
-    if (res.code !== 0) throw new Error(`readDoc failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(
+      () => this.client.docx.document.rawContent({ path: { document_id: documentId }, params: { lang: 0 } }),
+      'readDoc'
+    );
     return { content: res.data.content };
   }
 
   async createDoc(title, folderId) {
-    const res = await this.client.docx.document.create({ data: { title, folder_token: folderId || '' } });
-    if (res.code !== 0) throw new Error(`createDoc failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(
+      () => this.client.docx.document.create({ data: { title, folder_token: folderId || '' } }),
+      'createDoc'
+    );
     return { documentId: res.data.document?.document_id };
   }
 
   async getDocBlocks(documentId) {
-    const res = await this.client.docx.documentBlock.list({ path: { document_id: documentId }, params: { page_size: 500 } });
-    if (res.code !== 0) throw new Error(`getDocBlocks failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(
+      () => this.client.docx.documentBlock.list({ path: { document_id: documentId }, params: { page_size: 500 } }),
+      'getDocBlocks'
+    );
     return { items: res.data.items || [] };
   }
 
   // --- Bitable ---
 
   async listBitableTables(appToken) {
-    const res = await this.client.bitable.appTable.list({ path: { app_token: appToken } });
-    if (res.code !== 0) throw new Error(`listTables failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(() => this.client.bitable.appTable.list({ path: { app_token: appToken } }), 'listTables');
     return { items: res.data.items || [] };
   }
 
   async listBitableFields(appToken, tableId) {
-    const res = await this.client.bitable.appTableField.list({ path: { app_token: appToken, table_id: tableId } });
-    if (res.code !== 0) throw new Error(`listFields failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(() => this.client.bitable.appTableField.list({ path: { app_token: appToken, table_id: tableId } }), 'listFields');
     return { items: res.data.items || [] };
   }
 
@@ -224,55 +281,46 @@ class LarkOfficialClient {
     if (sort) data.sort = sort;
     if (pageSize) data.page_size = pageSize;
     if (pageToken) data.page_token = pageToken;
-    const res = await this.client.bitable.appTableRecord.search({
-      path: { app_token: appToken, table_id: tableId },
-      data,
-    });
-    if (res.code !== 0) throw new Error(`searchRecords failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(
+      () => this.client.bitable.appTableRecord.search({ path: { app_token: appToken, table_id: tableId }, data }),
+      'searchRecords'
+    );
     return { items: res.data.items || [], total: res.data.total, hasMore: res.data.has_more };
   }
 
   async createBitableRecord(appToken, tableId, fields) {
-    const res = await this.client.bitable.appTableRecord.create({
-      path: { app_token: appToken, table_id: tableId },
-      data: { fields },
-    });
-    if (res.code !== 0) throw new Error(`createRecord failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(
+      () => this.client.bitable.appTableRecord.create({ path: { app_token: appToken, table_id: tableId }, data: { fields } }),
+      'createRecord'
+    );
     return { recordId: res.data.record?.record_id };
   }
 
   async updateBitableRecord(appToken, tableId, recordId, fields) {
-    const res = await this.client.bitable.appTableRecord.update({
-      path: { app_token: appToken, table_id: tableId, record_id: recordId },
-      data: { fields },
-    });
-    if (res.code !== 0) throw new Error(`updateRecord failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(
+      () => this.client.bitable.appTableRecord.update({ path: { app_token: appToken, table_id: tableId, record_id: recordId }, data: { fields } }),
+      'updateRecord'
+    );
     return { recordId: res.data.record?.record_id };
   }
 
   // --- Wiki ---
 
   async listWikiSpaces() {
-    const res = await this.client.wiki.space.list({ params: { page_size: 50 } });
-    if (res.code !== 0) throw new Error(`listSpaces failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(() => this.client.wiki.space.list({ params: { page_size: 50 } }), 'listSpaces');
     return { items: res.data.items || [] };
   }
 
   async searchWiki(query) {
-    const res = await this.client.request({
-      method: 'POST',
-      url: '/open-apis/suite/docs-api/search/object',
-      data: { search_key: query, count: 20, offset: 0, owner_ids: [], chat_ids: [], docs_types: ['wiki'] },
-    });
-    if (res.code !== 0) throw new Error(`searchWiki failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(
+      () => this.client.request({ method: 'POST', url: '/open-apis/suite/docs-api/search/object', data: { search_key: query, count: 20, offset: 0, owner_ids: [], chat_ids: [], docs_types: ['wiki'] } }),
+      'searchWiki'
+    );
     return { items: res.data.docs_entities || [] };
   }
 
   async getWikiNode(spaceId, nodeToken) {
-    const res = await this.client.wiki.space.getNode({
-      params: { token: nodeToken },
-    });
-    if (res.code !== 0) throw new Error(`getNode failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(() => this.client.wiki.space.getNode({ params: { token: nodeToken } }), 'getNode');
     return res.data.node;
   }
 
@@ -280,11 +328,10 @@ class LarkOfficialClient {
     const params = { page_size: 50 };
     if (parentNodeToken) params.parent_node_token = parentNodeToken;
     if (pageToken) params.page_token = pageToken;
-    const res = await this.client.wiki.spaceNode.list({
-      path: { space_id: spaceId },
-      params,
-    });
-    if (res.code !== 0) throw new Error(`listNodes failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(
+      () => this.client.wiki.spaceNode.list({ path: { space_id: spaceId }, params }),
+      'listNodes'
+    );
     return { items: res.data.items || [], hasMore: res.data.has_more };
   }
 
@@ -293,16 +340,15 @@ class LarkOfficialClient {
   async listFiles(folderToken, { pageSize = 50, pageToken } = {}) {
     const params = { page_size: pageSize, folder_token: folderToken || '' };
     if (pageToken) params.page_token = pageToken;
-    const res = await this.client.drive.file.list({ params });
-    if (res.code !== 0) throw new Error(`listFiles failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(() => this.client.drive.file.list({ params }), 'listFiles');
     return { items: res.data.files || [], hasMore: res.data.has_more };
   }
 
   async createFolder(name, parentToken) {
-    const res = await this.client.drive.file.createFolder({
-      data: { name, folder_token: parentToken || '' },
-    });
-    if (res.code !== 0) throw new Error(`createFolder failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(
+      () => this.client.drive.file.createFolder({ data: { name, folder_token: parentToken || '' } }),
+      'createFolder'
+    );
     return { token: res.data.token };
   }
 
@@ -312,11 +358,10 @@ class LarkOfficialClient {
     const data = {};
     if (emails) data.emails = Array.isArray(emails) ? emails : [emails];
     if (mobiles) data.mobiles = Array.isArray(mobiles) ? mobiles : [mobiles];
-    const res = await this.client.contact.user.batchGetId({
-      data,
-      params: { user_id_type: 'open_id' },
-    });
-    if (res.code !== 0) throw new Error(`findUser failed (${res.code}): ${res.msg}`);
+    const res = await this._safeSDKCall(
+      () => this.client.contact.user.batchGetId({ data, params: { user_id_type: 'open_id' } }),
+      'findUser'
+    );
     return { userList: res.data.user_list || [] };
   }
 
@@ -327,8 +372,10 @@ class LarkOfficialClient {
     let pageToken;
     let hasMore = true;
     while (hasMore) {
-      const res = await this.client.im.chat.list({ params: { page_size: 100, page_token: pageToken } });
-      if (res.code !== 0) throw new Error(`listAllChats failed (${res.code}): ${res.msg}`);
+      const res = await this._safeSDKCall(
+        () => this.client.im.chat.list({ params: { page_size: 100, page_token: pageToken } }),
+        'listAllChats'
+      );
       allChats.push(...(res.data.items || []));
       pageToken = res.data.page_token;
       hasMore = res.data.has_more && !!pageToken;
@@ -336,6 +383,72 @@ class LarkOfficialClient {
     return allChats;
   }
 
+  // --- Safe SDK Call (extracts real Feishu error from AxiosError) ---
+
+  async _safeSDKCall(fn, label = 'API') {
+    try {
+      const res = await fn();
+      if (res.code !== 0) throw new Error(`${label} failed (${res.code}): ${res.msg}`);
+      return res;
+    } catch (err) {
+      // Lark SDK uses axios; extract actual Feishu error from response body
+      if (err.response?.data) {
+        const d = err.response.data;
+        const code = d.code ?? d.error ?? 'unknown';
+        const msg = d.msg ?? d.error_description ?? d.message ?? JSON.stringify(d);
+        throw new Error(`${label} failed (HTTP ${err.response.status}, code=${code}): ${msg}`);
+      }
+      throw err;
+    }
+  }
+
+  // --- Chat Search (keyword-based, works even if bot isn't in the group's list) ---
+
+  async chatSearch(query) {
+    const res = await this._safeSDKCall(
+      () => this.client.im.chat.search({ params: { query, page_size: 20 } }),
+      'chatSearch'
+    );
+    return res.data.items || [];
+  }
+
+  // --- User Name Resolution ---
+
+  async getUserById(userId, userIdType = 'open_id') {
+    if (this._userNameCache.has(userId)) return this._userNameCache.get(userId);
+    try {
+      const res = await this.client.contact.user.get({
+        path: { user_id: userId },
+        params: { user_id_type: userIdType },
+      });
+      if (res.code === 0 && res.data?.user?.name) {
+        this._userNameCache.set(userId, res.data.user.name);
+        return res.data.user.name;
+      }
+    } catch {}
+    return null;
+  }
+
+  async _populateSenderNames(items) {
+    // Collect unique sender IDs that aren't cached
+    const unknownIds = new Set();
+    for (const item of items) {
+      if (item.senderId && !this._userNameCache.has(item.senderId)) {
+        unknownIds.add(item.senderId);
+      }
+    }
+    // Batch resolve (sequential, with caching to avoid duplicate calls)
+    for (const id of unknownIds) {
+      await this.getUserById(id);
+    }
+    // Populate senderName field
+    for (const item of items) {
+      if (item.senderId) {
+        item.senderName = this._userNameCache.get(item.senderId) || null;
+      }
+    }
+  }
+
   // --- Helpers ---
 
   _formatMessage(m) {

package/src/setup.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/**
+ * Interactive setup wizard for feishu-user-plugin
+ *
+ * Writes MCP config to ~/.claude.json (or .mcp.json) with credentials.
+ * Does NOT require cloning the repo.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+const ask = (q) => new Promise(resolve => rl.question(q, resolve));
+
+const CLAUDE_JSON_PATH = path.join(process.env.HOME || '', '.claude.json');
+const SERVER_NAME = 'feishu-user-plugin';
+
+async function main() {
+  console.log('='.repeat(60));
+  console.log('  feishu-user-plugin Setup Wizard');
+  console.log('='.repeat(60));
+  console.log('');
+
+  // Check existing config
+  let config = {};
+  let existingEnv = {};
+  try {
+    config = JSON.parse(fs.readFileSync(CLAUDE_JSON_PATH, 'utf8'));
+    const existing = config.mcpServers?.[SERVER_NAME]?.env || config.mcpServers?.feishu?.env;
+    if (existing) {
+      existingEnv = existing;
+      console.log('Found existing feishu-user-plugin config in ~/.claude.json');
+      const update = await ask('Update existing config? (Y/n): ');
+      if (update.toLowerCase() === 'n') {
+        console.log('Cancelled.');
+        rl.close();
+        return;
+      }
+    }
+  } catch {}
+
+  // Collect credentials
+  console.log('\n--- App Credentials ---');
+  console.log('Team members: press Enter to use the shared defaults.');
+  console.log('External users: get these from https://open.feishu.cn/app\n');
+
+  const defaultAppId = existingEnv.LARK_APP_ID || '';
+  const defaultAppSecret = existingEnv.LARK_APP_SECRET || '';
+
+  let appId = await ask(`LARK_APP_ID [${defaultAppId || 'required'}]: `);
+  appId = appId.trim() || defaultAppId;
+  if (!appId) {
+    console.error('Error: LARK_APP_ID is required.');
+    rl.close();
+    process.exit(1);
+  }
+
+  let appSecret = await ask(`LARK_APP_SECRET [${defaultAppSecret ? '***' : 'required'}]: `);
+  appSecret = appSecret.trim() || defaultAppSecret;
+  if (!appSecret) {
+    console.error('Error: LARK_APP_SECRET is required.');
+    rl.close();
+    process.exit(1);
+  }
+
+  // Validate app credentials
+  console.log('\nValidating app credentials...');
+  try {
+    const res = 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 data = await res.json();
+    if (data.app_access_token) {
+      console.log('App credentials: VALID');
+    } else {
+      console.error(`App credentials: INVALID — ${data.msg || JSON.stringify(data)}`);
+      console.error('Please check your LARK_APP_ID and LARK_APP_SECRET.');
+      rl.close();
+      process.exit(1);
+    }
+  } catch (e) {
+    console.warn(`Could not validate: ${e.message}. Continuing anyway.`);
+  }
+
+  // Cookie
+  console.log('\n--- Cookie ---');
+  console.log('Get your cookie from feishu.cn (Network tab → first request → Cookie header).');
+  console.log('Or let Claude Code + Playwright extract it automatically after setup.\n');
+
+  const existingCookie = existingEnv.LARK_COOKIE;
+  const hasCookie = existingCookie && existingCookie !== 'PLACEHOLDER' && existingCookie.includes('session=');
+  if (hasCookie) {
+    console.log('Existing cookie found (has session token).');
+    const keepCookie = await ask('Keep existing cookie? (Y/n): ');
+    if (keepCookie.toLowerCase() === 'n') {
+      console.log('You can update it later or use Playwright extraction.');
+    }
+  } else {
+    console.log('No valid cookie found. You can add it later via:');
+    console.log('  1. Tell Claude Code: "帮我设置飞书 Cookie" (with Playwright MCP)');
+    console.log('  2. Manual: DevTools → Network → Cookie header → paste into config');
+  }
+
+  const cookie = hasCookie ? existingCookie : 'SETUP_NEEDED';
+
+  // UAT
+  const existingUAT = existingEnv.LARK_USER_ACCESS_TOKEN;
+  const existingRT = existingEnv.LARK_USER_REFRESH_TOKEN;
+  const hasUAT = existingUAT && existingUAT !== 'PLACEHOLDER' && existingUAT.length > 20;
+
+  if (!hasUAT) {
+    console.log('\n--- OAuth UAT ---');
+    console.log('UAT not configured. After setup, run:');
+    console.log('  npx feishu-user-plugin oauth');
+    console.log('This will open a browser for OAuth consent.');
+  }
+
+  // Write config
+  console.log('\n--- Writing Config ---');
+
+  if (!config.mcpServers) config.mcpServers = {};
+  config.mcpServers[SERVER_NAME] = {
+    command: 'npx',
+    args: ['-y', 'feishu-user-plugin'],
+    env: {
+      LARK_COOKIE: cookie,
+      LARK_APP_ID: appId,
+      LARK_APP_SECRET: appSecret,
+      LARK_USER_ACCESS_TOKEN: hasUAT ? existingUAT : 'SETUP_NEEDED',
+      LARK_USER_REFRESH_TOKEN: hasUAT ? (existingRT || '') : '',
+    },
+  };
+
+  // Remove old 'feishu' entry if exists (consolidate)
+  if (config.mcpServers.feishu && config.mcpServers[SERVER_NAME]) {
+    delete config.mcpServers.feishu;
+  }
+
+  fs.writeFileSync(CLAUDE_JSON_PATH, JSON.stringify(config, null, 2) + '\n');
+  console.log(`Written to ${CLAUDE_JSON_PATH}`);
+
+  // Also write .env for oauth.js to use
+  const envPath = path.join(__dirname, '..', '.env');
+  const envContent = [
+    `LARK_APP_ID=${appId}`,
+    `LARK_APP_SECRET=${appSecret}`,
+    cookie !== 'SETUP_NEEDED' ? `LARK_COOKIE=${cookie}` : '',
+    hasUAT ? `LARK_USER_ACCESS_TOKEN=${existingUAT}` : '',
+    hasUAT && existingRT ? `LARK_USER_REFRESH_TOKEN=${existingRT}` : '',
+  ].filter(Boolean).join('\n') + '\n';
+  fs.writeFileSync(envPath, envContent);
+
+  // Summary
+  console.log('\n' + '='.repeat(60));
+  console.log('  Setup Complete!');
+  console.log('='.repeat(60));
+  console.log('');
+
+  const todo = [];
+  if (cookie === 'SETUP_NEEDED') todo.push('Get Cookie: tell Claude Code "帮我设置飞书 Cookie"');
+  if (!hasUAT) todo.push('Get UAT: run "npx feishu-user-plugin oauth"');
+  todo.push('Restart Claude Code');
+
+  console.log('Next steps:');
+  todo.forEach((t, i) => console.log(`  ${i + 1}. ${t}`));
+  console.log('');
+
+  rl.close();
+}
+
+main().catch(e => {
+  console.error('Setup failed:', e.message);
+  rl.close();
+  process.exit(1);
+});

package/src/test-comprehensive.js

@@ -274,7 +274,7 @@ async function testUAT() {
 }
 
 async function main() {
-  console.log('=== feishu-user-plugin v1.0.0 — Comprehensive Test ===\n');
+  console.log('=== feishu-user-plugin v1.1.0 — Comprehensive Test ===\n');
 
   await testUserIdentity();
   console.log('');