feishu-mcp 0.1.1 → 0.1.3

package/README.md

@@ -21,7 +21,11 @@
 你可以通过以下视频了解 MCP 的实际使用效果和操作流程：
 
 <a href="https://www.bilibili.com/video/BV1z7MdzoEfu/?vd_source=94c14da5a71aeb01f665f159dd3d89c8">
-  <img src="image/demo.png" alt="飞书 MCP 使用演示" width="800"/>
+  <img src="image/demo.png" alt="飞书 MCP 使用演示" width="300"/>
+</a>
+
+<a href="https://www.bilibili.com/video/BV18z3gzdE1w/?vd_source=94c14da5a71aeb01f665f159dd3d89c8">
+  <img src="image/demo_1.png" alt="飞书 MCP 使用演示" width="300"/>
 </a>
 
 > ⭐ **Star 本项目，第一时间获取最新功能和重要更新！** 关注项目可以让你不错过任何新特性、修复和优化，助你持续高效使用。你的支持也将帮助我们更好地完善和发展项目。⭐
@@ -44,13 +48,12 @@
 | **工具功能** | `convert_feishu_wiki_to_document_id`                         | Wiki链接转换          | 将Wiki链接转为文档ID | ✅ 已完成 |
 | | `get_feishu_image_resource`                                  | 获取图片资源            | 下载文档中的图片      | ✅ 已完成 |
 | | `get_feishu_whiteboard_content`                              | 获取画板内容 | 获取画板中的图形元素和结构(流程图、思维导图等) | ✅ 已完成 |
-| **高级功能** | 表格操作                                                         | 创建和编辑表格           | 结构化数据展示       | 🚧 计划中 |
-| | 图表插入                                                         | 支持各类数据可视化图表       | 数据展示和分析       | 🚧 计划中 |
+| **高级功能** | `create_feishu_table`                                         | 创建和编辑表格           | 结构化数据展示       | ✅ 已完成 |
 | | 流程图插入                                                        | 支持流程图和思维导图        | 流程梳理和可视化      | ✅ 已完成 |
 | 图片插入  | `upload_and_bind_image_to_block` | 支持插入本地和远程图片       | 修改文档内容        | ✅ 已完成 |
 | | 公式支持                                                         | 支持数学公式            | 学术和技术文档       | ✅ 已完成 |
 
-### 🎨 支持的样式功能
+### 🎨 支持的样式功能（基本支持md所有格式）
 
 - **文本样式**：粗体、斜体、下划线、删除线、行内代码
 - **文本颜色**：灰色、棕色、橙色、黄色、绿色、蓝色、紫色
@@ -61,6 +64,7 @@
 - **图片**：支持本地图片和网络图片
 - **公式**：在文本块中插入数学公式，支持LaTeX语法
 - **mermaid图表**：支持流程图、时序图、思维导图、类图、饼图等等
+- **表格**：支持创建多行列表格，单元格可包含文本、标题、列表、代码块等多种内容类型
 
 ---
 
@@ -71,8 +75,10 @@
 - ~~**批量增强**：新增批量更新、批量图片上传，单次操作效率提升50%~~ 0.0.15 ✅
 - **流程优化**：减少多步调用，实现一键完成复杂任务
 - ~~**支持多种凭证类型**：包括 tenant_access_token和 user_access_token，满足不同场景下的认证需求~~  (飞书应用配置发生变更) 0.0.16 ✅。
-- **支持cursor用户登录**：方便在cursor平台用户认证
+- ~~**支持cursor用户登录**：方便在cursor平台用户认证   不做了,没必要 ❌~~
 - ~~**支持mermaid图表**：流程图、时序图等等，丰富文档内容~~ 0.1.11 ✅
+- ~~**支持表格创建**：创建包含各种块类型的复杂表格，支持样式控制~~ 0.1.2 ✅
+- ~~**支持飞书多用户user认证**：一人部署，可以多人使用~~ 0.1.3 ✅
 
 ---
 
@@ -91,29 +97,10 @@
 ### 方式一：使用 NPM 快速运行
 
 ```bash
-npx feishu-mcp@latest --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥>
+npx feishu-mcp@latest --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥> --feishu_auth_type=<tenant/user>
 ```
 
-### 方式二：使用 Smithery 平台
-
-**已发布到 Smithery 平台，可访问：** https://smithery.ai/server/@cso1z/feishu-mcp
-
-### 方式三：本地运行
-
-
-#### 🌿 分支说明
-
-本项目采用主分支（main）+功能分支（feature/xxx）协作模式：
-
-- **main**  
-  稳定主线分支，始终保持可用、可部署状态。所有已验证和正式发布的功能都会合并到 main 分支。
-
-- **multi-user-token** 
-
-  多用户隔离与按用户授权的 Feishu Token 获取功能开发分支。该分支支持 userKey 参数、按用户获取和缓存 Token、自定义 Token 服务等高级特性，适用于需要多用户隔离和授权场景的开发与测试。
-  > ⚠️ 该分支为 beta 版本，功能更新相较 main 分支可能会有延后。如有相关需求请在 issue 区留言，我会优先同步最新功能到该分支。
-  
-
+### 方式二：本地运行
 1. **克隆仓库**
    ```bash
    git clone https://github.com/cso1z/Feishu-MCP.git
@@ -126,16 +113,6 @@ npx feishu-mcp@latest --feishu-app-id=<你的飞书应用ID> --feishu-app-secret
    ```
 
 3. **配置环境变量(复制一份.env.example保存为.env文件)**
-   
-   **macOS/Linux:**
-   ```bash
-   cp .env.example .env
-   ```
-   
-   **Windows:**
-   ```cmd
-   copy .env.example .env
-   ```
 
 4. **编辑 .env 文件**
   在项目根目录下找到并用任意文本编辑器打开 `.env` 文件，填写你的飞书应用凭证：
@@ -143,6 +120,7 @@ npx feishu-mcp@latest --feishu-app-id=<你的飞书应用ID> --feishu-app-secret
    FEISHU_APP_ID=cli_xxxxx
    FEISHU_APP_SECRET=xxxxx
    PORT=3333
+   FEISHU_AUTH_TYPE=tenant/user
    ```
 
 5. **运行服务器**
@@ -154,32 +132,12 @@ npx feishu-mcp@latest --feishu-app-id=<你的飞书应用ID> --feishu-app-secret
 
 ### 环境变量配置
 
-| 变量名 | 必需 | 描述                                            | 默认值 |
-|--------|------|-----------------------------------------------|-------|
-| `FEISHU_APP_ID` | ✅ | 飞书应用 ID                                       | - |
-| `FEISHU_APP_SECRET` | ✅ | 飞书应用密钥                                        | - |
-| `PORT` | ❌ | 服务器端口                                         | `3333` |
-| `FEISHU_AUTH_TYPE` | ❌ | 认证凭证类型，建议本地运行时使用 `user`（用户级，需OAuth授权），云端/生产环境使用 `tenant`（应用级，默认） | `tenant` |
-| `FEISHU_TOKEN_ENDPOINT` | ❌ | 获取 token 的接口地址，仅当自定义 token 管理时需要              | `http://localhost:3333/getToken` |
-
-> **注意：**
-> - 只有本地运行服务时支持 `user` 凭证，否则需配置 `FEISHU_TOKEN_ENDPOINT`，自行实现 token 获取与管理（可参考 `callbackService`、`feishuAuthService`）。
-> - `FEISHU_TOKEN_ENDPOINT` 接口参数：`client_id`, `client_secret`, `token_type`（可选，tenant/user）；返回参数：`access_token`, `needAuth`, `url`（需授权时）, `expires_in`（单位:s）。
-
-### 命令行参数
-
-| 参数 | 描述 | 默认值 |
-|------|------|-------|
-| `--port` | 服务器监听端口 | `3333` |
-| `--log-level` | 日志级别 (debug/info/log/warn/error/none) | `info` |
-| `--feishu-app-id` | 飞书应用 ID | - |
-| `--feishu-app-secret` | 飞书应用密钥 | - |
-| `--feishu-base-url` | 飞书API基础URL | `https://open.feishu.cn/open-apis` |
-| `--cache-enabled` | 是否启用缓存 | `true` |
-| `--cache-ttl` | 缓存生存时间（秒） | `3600` |
-| `--stdio` | 命令模式运行 | - |
-| `--help` | 显示帮助菜单 | - |
-| `--version` | 显示版本号 | - |
+| 变量名 | 必需 | 描述                                                                 | 默认值 |
+|--------|------|--------------------------------------------------------------------|-------|
+| `FEISHU_APP_ID` | ✅ | 飞书应用 ID                                                            | - |
+| `FEISHU_APP_SECRET` | ✅ | 飞书应用密钥                                                             | - |
+| `PORT` | ❌ | 服务器端口                                                              | `3333` |
+| `FEISHU_AUTH_TYPE` | ❌ | 认证凭证类型，使用 `user`（用户级,使用时是用户的身份操作飞书文档，需OAuth授权），使用 `tenant`（应用级，默认） | `tenant` |
 
 ### 配置文件方式（适用于 Cursor、Cline 等）
 
@@ -191,11 +149,12 @@ npx feishu-mcp@latest --feishu-app-id=<你的飞书应用ID> --feishu-app-secret
       "args": ["-y", "feishu-mcp", "--stdio"],
       "env": {
         "FEISHU_APP_ID": "<你的飞书应用ID>",
-        "FEISHU_APP_SECRET": "<你的飞书应用密钥>"
+        "FEISHU_APP_SECRET": "<你的飞书应用密钥>",
+        "FEISHU_AUTH_TYPE": "<tenant/user>"
       }
     },
     "feishu_local": {
-      "url": "http://localhost:3333/sse"
+      "url": "http://localhost:3333/sse?:userKey=123456"
     }
   }
 }
@@ -216,6 +175,8 @@ npx feishu-mcp@latest --feishu-app-id=<你的飞书应用ID> --feishu-app-secret
 3. ### **公式使用说明**：
    在文本块中可以混合使用普通文本和公式元素。公式使用LaTeX语法，如：`1+2=3`、`\frac{a}{b}`、`\sqrt{x}`等。支持在同一文本块中包含多个公式和普通文本。
 
+4. ### **使用飞书user认证**：
+   user认证与tenant认证在增加权限时是有区分的，所以**在初次由tenant切换到user时需要注意配置的权限**；为了区分不同的用户需要在配置mcp server服务的url增加query参数：userKey，**该值是用户的唯一标识 所以最好在设置时越随机越好**
 ---
 
 ## 🚨 故障排查

package/dist/mcp/feishuMcp.js

@@ -6,7 +6,7 @@ import { registerFeishuBlockTools } from './tools/feishuBlockTools.js';
 import { registerFeishuFolderTools } from './tools/feishuFolderTools.js';
 const serverInfo = {
     name: "Feishu MCP Server",
-    version: "0.1.0",
+    version: "0.1.3",
 };
 const serverOptions = {
     capabilities: { logging: {}, tools: {} },

package/dist/mcp/tools/feishuBlockTools.js

@@ -8,11 +8,11 @@ import { DocumentIdSchema, ParentBlockIdSchema, BlockIdSchema, IndexSchema, Star
 TextElementsArraySchema, 
 // CodeLanguageSchema,
 // CodeWrapSchema,
-BlockConfigSchema, MediaIdSchema, MediaExtraSchema, ImagesArraySchema,
+BlockConfigSchema, MediaIdSchema, MediaExtraSchema, ImagesArraySchema, 
 // MermaidCodeSchema,
 // ImageWidthSchema,
 // ImageHeightSchema
- } from '../../types/feishuSchema.js';
+TableCreateSchema } from '../../types/feishuSchema.js';
 /**
  * 注册飞书块相关的MCP工具
  * @param server MCP服务器实例
@@ -618,4 +618,45 @@ export function registerFeishuBlockTools(server, feishuService) {
             };
         }
     });
+    // 添加创建飞书表格工具
+    server.tool('create_feishu_table', 'Creates a table block in a Feishu document with specified rows and columns. Each cell can contain different types of content blocks (text, lists, code, etc.). This tool creates the complete table structure including table cells and their content. Note: For Feishu wiki links (https://xxx.feishu.cn/wiki/xxx) you must first use convert_feishu_wiki_to_document_id tool to obtain a compatible document ID.', {
+        documentId: DocumentIdSchema,
+        parentBlockId: ParentBlockIdSchema,
+        index: IndexSchema,
+        tableConfig: TableCreateSchema,
+    }, async ({ documentId, parentBlockId, index = 0, tableConfig }) => {
+        try {
+            if (!feishuService) {
+                return {
+                    content: [{ type: 'text', text: '飞书服务未初始化，请检查配置' }],
+                };
+            }
+            Logger.info(`开始创建飞书表格，文档ID: ${documentId}，父块ID: ${parentBlockId}，表格大小: ${tableConfig.rowSize}x${tableConfig.columnSize}，插入位置: ${index}`);
+            const result = await feishuService.createTableBlock(documentId, parentBlockId, tableConfig, index);
+            // 构建返回信息
+            let resultText = `表格创建成功！\n\n表格大小: ${tableConfig.rowSize}x${tableConfig.columnSize}\n`;
+            // 如果有图片token，显示图片信息
+            if (result.imageTokens && result.imageTokens.length > 0) {
+                resultText += `\n\n📸 发现 ${result.imageTokens.length} 个图片:\n`;
+                result.imageTokens.forEach((imageToken, index) => {
+                    resultText += `${index + 1}. 坐标(${imageToken.row}, ${imageToken.column}) - blockId: ${imageToken.blockId}\n`;
+                });
+                resultText += "你需要使用upload_and_bind_image_to_block工具绑定图片";
+            }
+            resultText += `\n\n完整结果:\n${JSON.stringify(result, null, 2)}`;
+            return {
+                content: [{
+                        type: 'text',
+                        text: resultText
+                    }],
+            };
+        }
+        catch (error) {
+            Logger.error(`创建飞书表格失败:`, error);
+            const errorMessage = formatErrorMessage(error);
+            return {
+                content: [{ type: 'text', text: `创建飞书表格失败: ${errorMessage}` }],
+            };
+        }
+    });
 }

package/dist/mcp/tools/feishuTools.js

@@ -107,11 +107,14 @@ export function registerFeishuTools(server, feishuService) {
             // 检查是否有 block_type 为 43 的块（画板块）
             const whiteboardBlocks = blocks.filter((block) => block.block_type === 43);
             const hasWhiteboardBlocks = whiteboardBlocks.length > 0;
+            // 检查是否有 block_type 为 27 的块（图片块）
+            const imageBlocks = blocks.filter((block) => block.block_type === 27);
+            const hasImageBlocks = imageBlocks.length > 0;
             let responseText = JSON.stringify(blocks, null, 2);
             if (hasWhiteboardBlocks) {
                 responseText += '\n\n⚠️ 检测到画板块 (block_type: 43)！\n';
-                responseText += `发现 ${whiteboardBlocks.length} 个画板块。画板块包含丰富的图形内容，如形状、文本、思维导图等。\n`;
-                responseText += '建议使用 get_feishu_whiteboard_content 工具来获取画板的具体内容和结构。\n';
+                responseText += `发现 ${whiteboardBlocks.length} 个画板块。\n`;
+                responseText += '💡 提示：如果您需要获取画板的具体内容（如流程图、思维导图等），可以使用 get_feishu_whiteboard_content 工具。\n';
                 responseText += '画板信息:\n';
                 whiteboardBlocks.forEach((block, index) => {
                     responseText += `  ${index + 1}. 块ID: ${block.block_id}`;
@@ -120,7 +123,21 @@ export function registerFeishuTools(server, feishuService) {
                     }
                     responseText += '\n';
                 });
-                responseText += '请使用上述画板ID调用 get_feishu_whiteboard_content 工具。';
+                responseText += '📝 注意：只有在需要分析画板内容时才调用上述工具，仅了解文档结构时无需获取。';
+            }
+            if (hasImageBlocks) {
+                responseText += '\n\n🖼️ 检测到图片块 (block_type: 27)！\n';
+                responseText += `发现 ${imageBlocks.length} 个图片块。\n`;
+                responseText += '💡 提示：如果您需要查看图片的具体内容，可以使用 get_feishu_image_resource 工具下载图片。\n';
+                responseText += '图片信息:\n';
+                imageBlocks.forEach((block, index) => {
+                    responseText += `  ${index + 1}. 块ID: ${block.block_id}`;
+                    if (block.image && block.image.token) {
+                        responseText += `, 媒体ID: ${block.image.token}`;
+                    }
+                    responseText += '\n';
+                });
+                responseText += '📝 注意：只有在需要查看图片内容时才调用上述工具，仅了解文档结构时无需获取。';
             }
             return {
                 content: [{ type: 'text', text: responseText }],

package/dist/server.js

@@ -6,7 +6,8 @@ import { randomUUID } from 'node:crypto';
 import { Logger } from './utils/logger.js';
 import { SSEConnectionManager } from './manager/sseConnectionManager.js';
 import { FeishuMcp } from './mcp/feishuMcp.js';
-import { callback, getTokenByParams } from './services/callbackService.js';
+import { callback } from './services/callbackService.js';
+import { UserAuthManager, UserContextManager, getBaseUrl, TokenCacheManager } from './utils/auth';
 export class FeishuMcpServer {
     constructor() {
         Object.defineProperty(this, "connectionManager", {
@@ -15,7 +16,23 @@ export class FeishuMcpServer {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "userAuthManager", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "userContextManager", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this.connectionManager = new SSEConnectionManager();
+        this.userAuthManager = UserAuthManager.getInstance();
+        this.userContextManager = UserContextManager.getInstance();
+        // 初始化TokenCacheManager，确保在启动时从文件加载缓存
+        TokenCacheManager.getInstance();
     }
     async connect(transport) {
         const server = new FeishuMcp();
@@ -143,9 +160,18 @@ export class FeishuMcpServer {
             }
         });
         app.get('/sse', async (req, res) => {
+            // 获取 userKey 参数
+            let userKey = req.query.userKey;
             const sseTransport = new SSEServerTransport('/messages', res);
             const sessionId = sseTransport.sessionId;
-            Logger.log(`[SSE Connection] New SSE connection established for sessionId ${sessionId}   params:${JSON.stringify(req.params)} headers:${JSON.stringify(req.headers)} `);
+            // 如果 userKey 为空，使用 sessionId 替代
+            if (!userKey) {
+                userKey = sessionId;
+            }
+            Logger.log(`[SSE Connection] New SSE connection established for sessionId ${sessionId}, userKey: ${userKey}, params:${JSON.stringify(req.params)} headers:${JSON.stringify(req.headers)} `);
+            // 创建用户会话映射
+            this.userAuthManager.createSession(sessionId, userKey);
+            Logger.log(`[UserAuth] Created session mapping: sessionId=${sessionId}, userKey=${userKey}`);
             this.connectionManager.addConnection(sessionId, sseTransport, req, res);
             try {
                 const tempServer = new FeishuMcp();
@@ -155,6 +181,8 @@ export class FeishuMcpServer {
             catch (error) {
                 Logger.error(`[SSE Connection] Error connecting server to transport for ${sessionId}:`, error);
                 this.connectionManager.removeConnection(sessionId);
+                // 清理用户会话映射
+                this.userAuthManager.removeSession(sessionId);
                 if (!res.writableEnded) {
                     res.status(500).end('Failed to connect MCP server to transport');
                 }
@@ -163,7 +191,9 @@ export class FeishuMcpServer {
         });
         app.post('/messages', async (req, res) => {
             const sessionId = req.query.sessionId;
-            Logger.info(`[SSE messages] Received message with sessionId: ${sessionId}, params: ${JSON.stringify(req.query)}, body: ${JSON.stringify(req.body)}`);
+            // 通过 sessionId 获取 userKey
+            const userKey = this.userAuthManager.getUserKeyBySessionId(sessionId);
+            Logger.info(`[SSE messages] Received message with sessionId: ${sessionId}, userKey: ${userKey}, params: ${JSON.stringify(req.query)}, body: ${JSON.stringify(req.body)}`);
             if (!sessionId) {
                 res.status(400).send('Missing sessionId query parameter');
                 return;
@@ -176,27 +206,17 @@ export class FeishuMcpServer {
                     .send(`No active connection found for sessionId: ${sessionId}`);
                 return;
             }
-            await transport.handlePostMessage(req, res);
+            // 获取 baseUrl
+            const baseUrl = getBaseUrl(req);
+            // 在用户上下文中执行 transport.handlePostMessage
+            this.userContextManager.run({
+                userKey: userKey || '',
+                baseUrl: baseUrl
+            }, async () => {
+                await transport.handlePostMessage(req, res);
+            });
         });
         app.get('/callback', callback);
-        app.get('/getToken', async (req, res) => {
-            const { client_id, client_secret, token_type } = req.query;
-            if (!client_id || !client_secret) {
-                res.status(400).json({ code: 400, msg: '缺少 client_id 或 client_secret' });
-                return;
-            }
-            try {
-                const tokenResult = await getTokenByParams({
-                    client_id: client_id,
-                    client_secret: client_secret,
-                    token_type: token_type
-                });
-                res.json({ code: 0, msg: 'success', data: tokenResult });
-            }
-            catch (e) {
-                res.status(500).json({ code: 500, msg: e.message || '获取token失败' });
-            }
-        });
         app.listen(port, '0.0.0.0', () => {
             Logger.info(`HTTP server listening on port ${port}`);
             Logger.info(`SSE endpoint available at http://localhost:${port}/sse`);

package/dist/services/baseService.js

@@ -1,26 +1,14 @@
 import axios, { AxiosError } from 'axios';
 import FormData from 'form-data';
 import { Logger } from '../utils/logger.js';
-import { formatErrorMessage } from '../utils/error.js';
+import { formatErrorMessage, AuthRequiredError } from '../utils/error.js';
+import { Config } from '../utils/config.js';
+import { TokenCacheManager, UserContextManager, AuthUtils } from '../utils/auth';
 /**
  * API服务基类
  * 提供通用的HTTP请求处理和认证功能
  */
 export class BaseApiService {
-    constructor() {
-        Object.defineProperty(this, "accessToken", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: ''
-        });
-        Object.defineProperty(this, "tokenExpireTime", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: null
-        });
-    }
     /**
      * 处理API错误
      * @param error 错误对象
@@ -66,9 +54,16 @@ export class BaseApiService {
      * @param needsAuth 是否需要认证
      * @param additionalHeaders 附加请求头
      * @param responseType 响应类型
+     * @param retry 是否允许重试，默认为false
      * @returns 响应数据
      */
-    async request(endpoint, method = 'GET', data, needsAuth = true, additionalHeaders, responseType) {
+    async request(endpoint, method = 'GET', data, needsAuth = true, additionalHeaders, responseType, retry = false) {
+        // 获取用户上下文
+        const userContextManager = UserContextManager.getInstance();
+        const userKey = userContextManager.getUserKey();
+        const baseUrl = userContextManager.getBaseUrl();
+        const clientKey = AuthUtils.generateClientKey(userKey);
+        Logger.debug(`[BaseService] Request context - userKey: ${userKey}, baseUrl: ${baseUrl}`);
         try {
             // 构建请求URL
             const url = `${this.getBaseUrl()}${endpoint}`;
@@ -86,7 +81,7 @@ export class BaseApiService {
             }
             // 添加认证令牌
             if (needsAuth) {
-                const accessToken = await this.getAccessToken();
+                const accessToken = await this.getAccessToken(userKey);
                 headers['Authorization'] = `Bearer ${accessToken}`;
             }
             // 记录请求信息
@@ -130,25 +125,26 @@ export class BaseApiService {
             return response.data.data;
         }
         catch (error) {
-            // 处理401错误，可能是令牌过期
-            if (error instanceof AxiosError && error.response?.status === 401) {
-                // 清除当前令牌，下次请求会重新获取
-                this.accessToken = '';
-                this.tokenExpireTime = null;
-                Logger.warn('访问令牌可能已过期，已清除缓存的令牌');
-                // 如果这是重试请求，避免无限循环
-                if (error.isRetry) {
-                    this.handleApiError(error, `API请求失败 (${endpoint})`);
+            const config = Config.getInstance().feishu;
+            // 处理授权异常
+            if (error instanceof AuthRequiredError) {
+                return this.handleAuthFailure(config.authType === "tenant", clientKey, baseUrl, userKey);
+            }
+            // 处理认证相关错误（401, 403等）
+            if (error instanceof AxiosError && error.response && (error.response.status >= 400 || error.response.status <= 499)) {
+                Logger.warn(`认证失败 (${error.response.status}): ${endpoint}`);
+                // 获取配置和token缓存管理器
+                const tokenCacheManager = TokenCacheManager.getInstance();
+                // 如果已经重试过，直接处理认证失败
+                if (retry) {
+                    return this.handleAuthFailure(config.authType === "tenant", clientKey, baseUrl, userKey);
                 }
-                // 重试请求
-                Logger.info('重试请求...');
-                try {
-                    return await this.request(endpoint, method, data, needsAuth, additionalHeaders);
+                // 根据认证类型处理token过期
+                if (config.authType === 'tenant') {
+                    return this.handleTenantTokenExpired(tokenCacheManager, clientKey, endpoint, method, data, needsAuth, additionalHeaders, responseType);
                 }
-                catch (retryError) {
-                    // 标记为重试请求
-                    retryError.isRetry = true;
-                    this.handleApiError(retryError, `重试API请求失败 (${endpoint})`);
+                else {
+                    return this.handleUserTokenExpired(tokenCacheManager, clientKey, endpoint, method, data, needsAuth, additionalHeaders, responseType, baseUrl, userKey);
                 }
             }
             // 处理其他错误
@@ -205,4 +201,96 @@ export class BaseApiService {
     async delete(endpoint, data, needsAuth = true) {
         return this.request(endpoint, 'DELETE', data, needsAuth);
     }
+    /**
+     * 处理认证失败
+     * @param tenant 是否是tenant
+     * @param clientKey 客户端键
+     * @param baseUrl 基础URL
+     * @param userKey 用户键
+     */
+    handleAuthFailure(tenant, clientKey, baseUrl, userKey) {
+        const tokenCacheManager = TokenCacheManager.getInstance();
+        if (tenant) {
+            // 租户模式：清除租户token缓存
+            Logger.info('租户模式：清除租户token缓存');
+            tokenCacheManager.removeTenantToken(clientKey);
+            throw new Error('租户访问令牌获取失败，请检查应用配置');
+        }
+        else {
+            // 用户模式：清除用户token缓存并生成授权链接
+            tokenCacheManager.removeUserToken(clientKey);
+            const authUrl = this.generateUserAuthUrl(baseUrl, userKey);
+            throw new Error(`你需要在给用户展示如下信息：/“请在浏览器打开以下链接进行授权：\n\n[点击授权](${authUrl})/n`);
+        }
+    }
+    /**
+     * 处理租户token过期
+     * @param tokenCacheManager token缓存管理器
+     * @param clientKey 客户端键
+     * @param endpoint 请求端点
+     * @param method 请求方法
+     * @param data 请求数据
+     * @param needsAuth 是否需要认证
+     * @param additionalHeaders 附加请求头
+     * @param responseType 响应类型
+     * @returns 响应数据
+     */
+    async handleTenantTokenExpired(tokenCacheManager, clientKey, endpoint, method, data, needsAuth, additionalHeaders, responseType) {
+        // 租户模式：直接清除租户token缓存
+        Logger.info('租户模式：清除租户token缓存');
+        tokenCacheManager.removeTenantToken(clientKey);
+        // 重试请求
+        Logger.info('重试租户请求...');
+        return await this.request(endpoint, method, data, needsAuth, additionalHeaders, responseType, true);
+    }
+    /**
+     * 处理用户token过期
+     * @param tokenCacheManager token缓存管理器
+     * @param clientKey 客户端键
+     * @param endpoint 请求端点
+     * @param method 请求方法
+     * @param data 请求数据
+     * @param needsAuth 是否需要认证
+     * @param additionalHeaders 附加请求头
+     * @param responseType 响应类型
+     * @returns 响应数据
+     */
+    async handleUserTokenExpired(tokenCacheManager, clientKey, endpoint, method, data, needsAuth, additionalHeaders, responseType, baseUrl, userKey) {
+        // 用户模式：检查用户token状态
+        const tokenStatus = tokenCacheManager.checkUserTokenStatus(clientKey);
+        Logger.debug(`用户token状态:`, tokenStatus);
+        if (tokenStatus.canRefresh && !tokenStatus.isExpired) {
+            // 有有效的refresh_token，设置token为过期状态，让下次请求时刷新
+            Logger.info('用户模式：token过期，将在下次请求时刷新');
+            const tokenInfo = tokenCacheManager.getUserTokenInfo(clientKey);
+            if (tokenInfo) {
+                // 设置access_token为过期，但保留refresh_token
+                tokenInfo.expires_at = Math.floor(Date.now() / 1000) - 1;
+                tokenCacheManager.cacheUserToken(clientKey, tokenInfo);
+            }
+            // 重试请求
+            Logger.info('重试用户请求...');
+            return await this.request(endpoint, method, data, needsAuth, additionalHeaders, responseType, true);
+        }
+        else {
+            // refresh_token已过期或不存在，直接清除缓存
+            Logger.warn('用户模式：refresh_token已过期，清除用户token缓存');
+            tokenCacheManager.removeUserToken(clientKey);
+            return this.handleAuthFailure(true, clientKey, baseUrl, userKey);
+        }
+    }
+    /**
+     * 生成用户授权URL
+     * @param baseUrl 基础URL
+     * @param userKey 用户键
+     * @returns 授权URL
+     */
+    generateUserAuthUrl(baseUrl, userKey) {
+        const { appId, appSecret } = Config.getInstance().feishu;
+        const clientKey = AuthUtils.generateClientKey(userKey);
+        const redirect_uri = `${baseUrl}/callback`;
+        const scope = encodeURIComponent('base:app:read bitable:app bitable:app:readonly board:whiteboard:node:read contact:user.employee_id:readonly docs:document.content:read docx:document docx:document.block:convert docx:document:create docx:document:readonly drive:drive drive:drive:readonly drive:file drive:file:upload sheets:spreadsheet sheets:spreadsheet:readonly space:document:retrieve space:folder:create wiki:space:read wiki:space:retrieve wiki:wiki wiki:wiki:readonly offline_access');
+        const state = AuthUtils.encodeState(appId, appSecret, clientKey, redirect_uri);
+        return `https://accounts.feishu.cn/open-apis/authen/v1/authorize?client_id=${appId}&redirect_uri=${encodeURIComponent(redirect_uri)}&scope=${scope}&state=${state}`;
+    }
 }