feishu-mcp 0.2.2 → 0.2.7

package/dist/cli/auth.js

@@ -0,0 +1,117 @@
+import { exec } from 'child_process';
+import { createServer as createNetServer } from 'net';
+import express from 'express';
+import { Config } from '../utils/config.js';
+import { AuthUtils, TokenCacheManager } from '../utils/auth/index.js';
+// callbackService 需延迟导入，避免其模块级 Config.getInstance() 在 CLI 启动时提前触发 yargs
+const AUTH_TIMEOUT_MS = 5 * 60 * 1000; // 5 分钟
+const POLL_INTERVAL_MS = 1000;
+/**
+ * 在系统默认浏览器中打开 URL（跨平台）
+ */
+function openBrowser(url) {
+    let cmd;
+    if (process.platform === 'win32') {
+        cmd = `cmd /c start "" "${url}"`;
+    }
+    else if (process.platform === 'darwin') {
+        cmd = `open "${url}"`;
+    }
+    else {
+        cmd = `xdg-open "${url}"`;
+    }
+    exec(cmd, (err) => {
+        if (err) {
+            process.stderr.write(`[feishu-mcp-tool] 无法自动打开浏览器，请手动访问上方授权链接\n`);
+        }
+    });
+}
+/**
+ * 检查端口是否可用
+ */
+function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = createNetServer();
+        server.once('error', () => resolve(false));
+        server.once('listening', () => {
+            server.close();
+            resolve(true);
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+/**
+ * 从起始端口开始寻找第一个可用端口（最多尝试 10 个）
+ */
+async function findAvailablePort(startPort) {
+    for (let port = startPort; port < startPort + 10; port++) {
+        if (await isPortAvailable(port))
+            return port;
+    }
+    return startPort; // fallback，让后续绑定时自然报错
+}
+/**
+ * 启动临时 callback express 服务器（延迟导入 callbackService 避免提前触发 Config）
+ */
+async function startCallbackServer(port) {
+    const { callback } = await import('../services/callbackService.js');
+    const app = express();
+    app.get('/callback', callback);
+    return new Promise((resolve, reject) => {
+        const server = app.listen(port, '127.0.0.1', () => resolve(server));
+        server.once('error', reject);
+    });
+}
+/**
+ * 轮询 TokenCacheManager，等待指定 clientKey 的有效 token 写入
+ */
+async function waitForToken(clientKey, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    const cache = TokenCacheManager.getInstance();
+    while (Date.now() < deadline) {
+        const status = cache.checkUserTokenStatus(clientKey);
+        if (status.isValid)
+            return true;
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    }
+    return false;
+}
+/**
+ * 处理 AuthRequiredError：启动 callback 服务器，打开浏览器，等待 token
+ * 成功后 token 已写入 TokenCacheManager，调用方可直接重试 ToolApi
+ * @throws Error 超时或端口绑定失败
+ */
+export async function handleAuthRequired(userKey) {
+    const config = Config.getInstance();
+    const { appId, appSecret } = config.feishu;
+    // 1. 寻找可用端口（从配置端口开始）
+    const port = await findAvailablePort(config.server.port);
+    const redirectUri = `http://localhost:${port}/callback`;
+    // 2. 计算 clientKey 和 state
+    const clientKey = AuthUtils.generateClientKey(userKey);
+    const state = AuthUtils.encodeState(appId, appSecret, clientKey, redirectUri);
+    // 3. 构造飞书 OAuth 授权 URL
+    const authUrl = `https://open.feishu.cn/open-apis/authen/v1/index` +
+        `?app_id=${encodeURIComponent(appId)}` +
+        `&redirect_uri=${encodeURIComponent(redirectUri)}` +
+        `&state=${encodeURIComponent(state)}`;
+    // 4. 启动临时 callback 服务器
+    let server;
+    try {
+        server = await startCallbackServer(port);
+    }
+    catch (err) {
+        throw new Error(`无法启动授权回调服务器（端口 ${port}）：${err}`);
+    }
+    // 5. 打开浏览器并向 stderr 输出提示（不污染 stdout）
+    openBrowser(authUrl);
+    process.stderr.write(`\n[feishu-mcp-tool] 需要飞书授权，已在浏览器打开授权页（5 分钟内有效）\n` +
+        `[feishu-mcp-tool] 授权链接：${authUrl}\n\n`);
+    // 6. 等待 token 写入
+    const ok = await waitForToken(clientKey, AUTH_TIMEOUT_MS);
+    // 7. 无论成功与否，关闭临时服务器
+    await new Promise((resolve) => server.close(() => resolve()));
+    if (!ok) {
+        throw new Error('飞书授权超时（5 分钟），请重新执行命令');
+    }
+}

package/dist/cli/commands/auth.js

@@ -0,0 +1,141 @@
+import { exec } from 'child_process';
+import { createServer as createNetServer } from 'net';
+import express from 'express';
+import { Config } from '../../utils/config.js';
+import { AuthUtils, TokenCacheManager } from '../../utils/auth/index.js';
+// callbackService 需延迟导入，避免其模块级 Config.getInstance() 在 CLI 启动时提前触发 yargs
+const AUTH_TIMEOUT_MS = 5 * 60 * 1000; // 5 分钟
+const POLL_INTERVAL_MS = 1000;
+/**
+ * 在系统默认浏览器中打开 URL（跨平台）
+ */
+export function openBrowser(url) {
+    let cmd;
+    if (process.platform === 'win32') {
+        cmd = `cmd /c start "" "${url}"`;
+    }
+    else if (process.platform === 'darwin') {
+        cmd = `open "${url}"`;
+    }
+    else {
+        cmd = `xdg-open "${url}"`;
+    }
+    exec(cmd, (err) => {
+        if (err) {
+            process.stderr.write(`[feishu-mcp-tool] 无法自动打开浏览器，请手动访问上方授权链接\n`);
+        }
+    });
+}
+/**
+ * 检查端口是否可用
+ */
+function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = createNetServer();
+        server.once('error', () => resolve(false));
+        server.once('listening', () => {
+            server.close();
+            resolve(true);
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+/**
+ * 从起始端口开始寻找第一个可用端口（最多尝试 10 个）
+ */
+async function findAvailablePort(startPort) {
+    for (let port = startPort; port < startPort + 10; port++) {
+        if (await isPortAvailable(port))
+            return port;
+    }
+    return startPort; // fallback，让后续绑定时自然报错
+}
+/**
+ * 启动临时 callback express 服务器（延迟导入 callbackService 避免提前触发 Config）
+ */
+async function startCallbackServer(port) {
+    const { callback } = await import('../../services/callbackService.js');
+    const app = express();
+    app.get('/callback', callback);
+    return new Promise((resolve, reject) => {
+        const server = app.listen(port, '127.0.0.1', () => resolve(server));
+        server.once('error', reject);
+    });
+}
+/**
+ * 轮询 TokenCacheManager，等待指定 clientKey 的有效 token 写入
+ */
+async function waitForToken(clientKey, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    const cache = TokenCacheManager.getInstance();
+    while (Date.now() < deadline) {
+        const status = cache.checkUserTokenStatus(clientKey);
+        if (status.isValid)
+            return true;
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    }
+    return false;
+}
+/**
+ * 处理 AuthRequiredError：启动 callback 服务器，打开浏览器，等待 token
+ * 成功后 token 已写入 TokenCacheManager，调用方可直接重试 ToolApi
+ * @throws Error 超时或端口绑定失败
+ */
+export async function handleAuthRequired(userKey) {
+    const config = Config.getInstance();
+    const { appId, appSecret } = config.feishu;
+    // 1. 寻找可用端口（从配置端口开始）
+    const port = await findAvailablePort(config.server.port);
+    const redirectUri = `http://localhost:${port}/callback`;
+    // 2. 计算 clientKey 和 state
+    const clientKey = AuthUtils.generateClientKey(userKey);
+    const state = AuthUtils.encodeState(appId, appSecret, clientKey, redirectUri);
+    // 3. 构造飞书 OAuth 授权 URL
+    const authUrl = `https://open.feishu.cn/open-apis/authen/v1/index` +
+        `?app_id=${encodeURIComponent(appId)}` +
+        `&redirect_uri=${encodeURIComponent(redirectUri)}` +
+        `&state=${encodeURIComponent(state)}`;
+    // 4. 启动临时 callback 服务器
+    let server;
+    try {
+        server = await startCallbackServer(port);
+    }
+    catch (err) {
+        throw new Error(`无法启动授权回调服务器（端口 ${port}）：${err}`);
+    }
+    // 5. 打开浏览器并向 stderr 输出提示（不污染 stdout）
+    openBrowser(authUrl);
+    process.stderr.write(`\n[feishu-mcp-tool] 需要飞书授权，已在浏览器打开授权页（5 分钟内有效）\n` +
+        `[feishu-mcp-tool] 授权链接：${authUrl}\n\n`);
+    // 6. 等待 token 写入
+    const ok = await waitForToken(clientKey, AUTH_TIMEOUT_MS);
+    // 7. 延迟关闭临时服务器，确保 /callback 的 HTTP 响应已发送完毕
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    await new Promise((resolve) => server.close(() => resolve()));
+    if (!ok) {
+        throw new Error('飞书授权超时（5 分钟），请重新执行命令');
+    }
+}
+/** 展示当前 token 授权状态 */
+export async function handleAuthStatus() {
+    const config = Config.getInstance();
+    const { authType, userKey } = config.feishu;
+    if (authType !== 'user') {
+        process.stdout.write(JSON.stringify({ authType, status: 'tenant 模式无需用户授权' }) + '\n');
+        return;
+    }
+    const clientKey = AuthUtils.generateClientKey(userKey);
+    const status = TokenCacheManager.getInstance().checkUserTokenStatus(clientKey);
+    process.stdout.write(JSON.stringify({ authType, userKey, ...status }) + '\n');
+}
+/** 清除当前用户 token 缓存 */
+export async function handleAuthLogout() {
+    const config = Config.getInstance();
+    const { userKey } = config.feishu;
+    const clientKey = AuthUtils.generateClientKey(userKey);
+    const ok = TokenCacheManager.getInstance().removeUserToken(clientKey);
+    process.stdout.write(JSON.stringify({
+        ok,
+        message: ok ? '已退出登录，token 已清除' : '未找到缓存的 token',
+    }) + '\n');
+}

package/dist/cli/commands/config.js

@@ -0,0 +1,86 @@
+import { resolve } from 'path';
+import { homedir } from 'os';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+export const GLOBAL_CONFIG_DIR = resolve(homedir(), '.cache', 'feishu-mcp');
+export const GLOBAL_CONFIG_FILE = resolve(GLOBAL_CONFIG_DIR, '.env');
+const CONFIG_KEYS = {
+    FEISHU_APP_ID: '飞书应用 App ID',
+    FEISHU_APP_SECRET: '飞书应用 App Secret',
+    FEISHU_AUTH_TYPE: '认证类型：tenant（应用身份）或 user（用户身份，支持 task/member）',
+    FEISHU_ENABLED_MODULES: '启用的功能模块，逗号分隔，可选值: document,task,member,calendar,all',
+    FEISHU_BASE_URL: '飞书 API 基础地址，默认 https://open.feishu.cn/open-apis',
+    FEISHU_SCOPE_VALIDATION: '是否启用权限校验：true 或 false，默认 true',
+    PORT: '服务监听端口，默认 3333',
+};
+/** 读取并解析 .env 文件为 key-value 对象 */
+export function readEnvFile(filePath) {
+    if (!existsSync(filePath))
+        return {};
+    const result = {};
+    for (const line of readFileSync(filePath, 'utf-8').split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const idx = trimmed.indexOf('=');
+        if (idx === -1)
+            continue;
+        result[trimmed.slice(0, idx).trim()] = trimmed.slice(idx + 1).trim();
+    }
+    return result;
+}
+/** 向 .env 文件写入或更新一个 key */
+export function writeEnvKey(filePath, key, value) {
+    mkdirSync(resolve(filePath, '..'), { recursive: true });
+    let content = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : '';
+    const regex = new RegExp(`^${key}=.*$`, 'm');
+    if (regex.test(content)) {
+        content = content.replace(regex, `${key}=${value}`);
+    }
+    else {
+        content += (content && !content.endsWith('\n') ? '\n' : '') + `${key}=${value}\n`;
+    }
+    writeFileSync(filePath, content, 'utf-8');
+}
+/** 展示当前生效配置 */
+export function handleConfigShow(envPath) {
+    const fileConfig = readEnvFile(GLOBAL_CONFIG_FILE);
+    const output = {
+        configFile: existsSync(GLOBAL_CONFIG_FILE) ? GLOBAL_CONFIG_FILE : null,
+        loadedFrom: envPath ?? null,
+        config: {
+            FEISHU_APP_ID: process.env.FEISHU_APP_ID ?? '(未设置)',
+            FEISHU_APP_SECRET: process.env.FEISHU_APP_SECRET
+                ? `${process.env.FEISHU_APP_SECRET.slice(0, 3)}****` : '(未设置)',
+            FEISHU_AUTH_TYPE: process.env.FEISHU_AUTH_TYPE ?? 'tenant (默认)',
+            FEISHU_ENABLED_MODULES: process.env.FEISHU_ENABLED_MODULES ?? 'document (默认)',
+            PORT: process.env.PORT ?? '3333 (默认)',
+        },
+        globalConfigFile: Object.keys(fileConfig).length ? fileConfig : '(文件不存在)',
+    };
+    process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+}
+/** 向配置文件写入 key=value，写入目标与当前加载来源保持一致 */
+export function handleConfigSet(key, value, envPath) {
+    if (!key || !value) {
+        process.stdout.write(JSON.stringify({
+            usage: 'feishu-mcp-tool config set <KEY> <VALUE>',
+            availableKeys: CONFIG_KEYS,
+        }, null, 2) + '\n');
+        process.exit(0);
+    }
+    if (!(key in CONFIG_KEYS)) {
+        process.stdout.write(JSON.stringify({
+            error: `未知配置项: ${key}`,
+            availableKeys: CONFIG_KEYS,
+        }) + '\n');
+        process.exit(1);
+    }
+    // 写入目标与读取来源一致：已有加载文件则写入该文件，否则写入全局配置文件
+    const targetFile = envPath ?? GLOBAL_CONFIG_FILE;
+    writeEnvKey(targetFile, key, value);
+    process.stdout.write(JSON.stringify({
+        ok: true,
+        file: targetFile,
+        set: { [key]: key.includes('SECRET') ? `${value.slice(0, 3)}****` : value },
+    }) + '\n');
+}

package/dist/cli/commands/guide.js

@@ -0,0 +1,68 @@
+import { openBrowser } from './auth.js';
+const GUIDE_URL = 'https://github.com/cso1z/Feishu-MCP/blob/cli/FEISHU_CONFIG.md';
+// 各模块的权限说明（摘要，完整列表见 FEISHU_CONFIG.md）
+const MODULE_SCOPE_DESC = {
+    document: { authTypes: 'tenant + user', desc: '文档读写、云盘、白板、知识库相关权限' },
+    task: { authTypes: 'user only', desc: 'task:task:write' },
+    member: { authTypes: 'user only', desc: 'contact:user.base:readonly 等联系人权限' },
+};
+/** 飞书 MCP 配置指南 */
+export function handleGuide() {
+    const authType = (process.env.FEISHU_AUTH_TYPE ?? 'tenant');
+    const rawModules = process.env.FEISHU_ENABLED_MODULES ?? 'document';
+    const enabledModules = rawModules.split(',').map(s => s.trim()).filter(Boolean);
+    const allModules = enabledModules.includes('all') ? Object.keys(MODULE_SCOPE_DESC) : enabledModules;
+    const port = process.env.PORT ?? '3333';
+    const guide = {
+        title: '飞书 MCP 配置指南',
+        detailedGuide: GUIDE_URL,
+        tip: `完整配置说明（含截图）请查阅：${GUIDE_URL}，已自动在浏览器打开，也可将此链接提供给用户手动访问`,
+        currentConfig: { authType, enabledModules },
+        steps: [
+            {
+                step: 1,
+                title: '创建飞书应用，获取 App ID 和 App Secret',
+                actions: [
+                    '访问飞书开放平台：https://open.feishu.cn/app',
+                    '点击「创建企业自建应用」',
+                    '进入应用详情 → 凭证与基础信息 → 获取 App ID 和 App Secret',
+                ],
+                commands: [
+                    'feishu-mcp-tool config set FEISHU_APP_ID <your-app-id>',
+                    'feishu-mcp-tool config set FEISHU_APP_SECRET <your-app-secret>',
+                ],
+            },
+            {
+                step: 2,
+                title: '申请应用权限',
+                note: `按需添加，仅需为已启用模块申请权限，完整 scopes 列表见：${GUIDE_URL}`,
+                enabledModules: allModules
+                    .filter(m => m in MODULE_SCOPE_DESC)
+                    .map(m => ({ module: m, ...MODULE_SCOPE_DESC[m] })),
+            },
+            ...(authType === 'user' ? [{
+                    step: 3,
+                    title: '配置 OAuth 回调地址',
+                    actions: [
+                        `飞书开放平台 → 安全设置 → 重定向 URL → 添加：http://localhost:${port}/callback`,
+                    ],
+                }] : []),
+            {
+                step: authType === 'user' ? 4 : 3,
+                title: '发布应用版本',
+                actions: ['可用范围选择「全部员工」', '提交审批，等待管理员通过'],
+            },
+            {
+                step: authType === 'user' ? 5 : 4,
+                title: '验证配置',
+                commands: [
+                    'feishu-mcp-tool config                           # 查看当前配置',
+                    'feishu-mcp-tool auth                             # 查看 token 状态',
+                    "feishu-mcp-tool get_feishu_root_folder_info '{}' # 测试接口连通性",
+                ],
+            },
+        ],
+    };
+    process.stdout.write(JSON.stringify(guide, null, 2) + '\n');
+    openBrowser(GUIDE_URL);
+}

package/dist/cli/dispatcher.js

@@ -0,0 +1,96 @@
+import { FeishuApiService } from '../services/feishuApiService.js';
+import { UserContextManager, TokenCacheManager, AuthUtils } from '../utils/auth/index.js';
+import { Config } from '../utils/config.js';
+import { handleAuthRequired } from './commands/auth.js';
+// Document toolApis
+import { createDocument, getDocumentInfo, getDocumentBlocks, searchDocuments, batchUpdateBlockText, batchCreateBlocks, deleteDocumentBlocks, getImageResource, uploadAndBindImageToBlock, createTable, getWhiteboardContent, fillWhiteboardWithPlantuml, getRootFolderInfo, getFolderFiles, createFolder, } from '../modules/document/toolApi/index.js';
+// Task toolApis
+import { createTasks, listTasks, updateTask, deleteTasks } from '../modules/task/toolApi/index.js';
+// Member toolApis
+import { getUsers } from '../modules/member/toolApi/index.js';
+/**
+ * 按模块组织的工具注册表，与 src/modules 目录划分保持一致
+ */
+const MODULE_REGISTRY = {
+    document: {
+        authType: 'tenant',
+        tools: {
+            create_feishu_document: (p, s) => createDocument(p, s),
+            get_feishu_document_info: (p, s) => getDocumentInfo(p, s),
+            get_feishu_document_blocks: (p, s) => getDocumentBlocks(p.documentId, s),
+            search_feishu_documents: (p, s) => searchDocuments(p, s),
+            batch_update_feishu_block_text: (p, s) => batchUpdateBlockText(p, s),
+            batch_create_feishu_blocks: (p, s) => batchCreateBlocks(p, s),
+            delete_feishu_document_blocks: (p, s) => deleteDocumentBlocks(p, s),
+            get_feishu_image_resource: (p, s) => getImageResource(p.mediaId, p.extra ?? '', s),
+            upload_and_bind_image_to_block: (p, s) => uploadAndBindImageToBlock(p, s),
+            create_feishu_table: (p, s) => createTable(p, s),
+            get_feishu_whiteboard_content: (p, s) => getWhiteboardContent(p.whiteboardId, s),
+            fill_whiteboard_with_plantuml: (p, s) => fillWhiteboardWithPlantuml(p, s),
+            get_feishu_root_folder_info: (_p, s) => getRootFolderInfo(s),
+            get_feishu_folder_files: (p, s) => getFolderFiles(p, s),
+            create_feishu_folder: (p, s) => createFolder(p, s),
+        },
+    },
+    task: {
+        authType: 'user',
+        tools: {
+            list_feishu_tasks: (p, s) => listTasks(p, s),
+            create_feishu_task: (p, s) => createTasks(p.tasks, s),
+            update_feishu_task: (p, s) => updateTask(p, s),
+            delete_feishu_task: (p, s) => deleteTasks(p.taskGuids, s),
+        },
+    },
+    member: {
+        authType: 'user',
+        tools: {
+            get_feishu_users: (p, s) => getUsers(p, s),
+        },
+    },
+};
+/** 将 MODULE_REGISTRY 展平为 toolName → handler 的查找表 */
+function buildFlatMap() {
+    const flat = {};
+    for (const mod of Object.values(MODULE_REGISTRY)) {
+        Object.assign(flat, mod.tools);
+    }
+    return flat;
+}
+const FLAT_TOOL_MAP = buildFlatMap();
+/**
+ * 返回支持的工具名称列表，按认证类型过滤
+ * tenant 模式下排除需要 user 认证的模块工具
+ */
+export function listTools(authType) {
+    const tools = [];
+    for (const mod of Object.values(MODULE_REGISTRY)) {
+        if (authType === 'tenant' && mod.authType === 'user')
+            continue;
+        tools.push(...Object.keys(mod.tools));
+    }
+    return tools;
+}
+/**
+ * 调度指定工具，注入用户上下文，处理 AuthRequiredError 并自动重试一次
+ */
+export async function dispatch(toolName, params) {
+    const handler = FLAT_TOOL_MAP[toolName];
+    if (!handler) {
+        throw new Error(`未知工具: "${toolName}"。可用工具：\n${listTools().join('\n')}`);
+    }
+    const config = Config.getInstance();
+    const userKey = config.feishu.userKey;
+    const userContextManager = UserContextManager.getInstance();
+    const apiService = FeishuApiService.getInstance();
+    const baseUrl = `http://localhost:${config.server.port}`;
+    const invoke = () => userContextManager.run({ userKey, baseUrl }, () => handler(params, apiService));
+    // 在 user 模式下，预先检查 token 是否有效，无效则触发授权流程
+    if (config.feishu.authType === 'user') {
+        const clientKey = AuthUtils.generateClientKey(userKey);
+        const status = TokenCacheManager.getInstance().checkUserTokenStatus(clientKey);
+        if (!status.isValid && !status.canRefresh) {
+            await handleAuthRequired(userKey);
+        }
+    }
+    return await invoke();
+}

package/dist/cli/index.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { resolve } from 'path';
+import { homedir } from 'os';
+import { existsSync } from 'fs';
+import { config as loadDotEnv } from 'dotenv';
+import { Logger } from '../utils/logger.js';
+import { dispatch, listTools } from './dispatcher.js';
+import { handleConfigShow, handleConfigSet } from './commands/config.js';
+import { handleAuthStatus, handleAuthLogout } from './commands/auth.js';
+import { handleGuide } from './commands/guide.js';
+// 按优先级查找 .env：CWD → ~/.cache/feishu-mcp（与 token 缓存同目录）
+const envCandidates = [
+    resolve(process.cwd(), '.env'),
+    resolve(homedir(), '.cache', 'feishu-mcp', '.env'),
+];
+const envPath = envCandidates.find(p => existsSync(p));
+if (envPath)
+    loadDotEnv({ path: envPath });
+// 禁用所有日志输出，保持 stdout 纯 JSON
+Logger.setEnabled(false);
+// key 为空字符串表示默认子命令（即直接执行父命令时）
+const COMMAND_REGISTRY = {
+    config: {
+        '': { description: '查看当前生效配置', handler: (_) => handleConfigShow(envPath) },
+        set: { description: '修改配置 <KEY> <VALUE>（不带参数可查看所有可用 KEY）', handler: (args) => handleConfigSet(args[0], args[1], envPath) },
+    },
+    auth: {
+        '': { description: '查看 token 授权状态', handler: (_) => handleAuthStatus() },
+        logout: { description: '清除已缓存的 token', handler: (_) => handleAuthLogout() },
+    },
+    guide: {
+        '': { description: '飞书应用配置指南（步骤说明）', handler: (_) => handleGuide() },
+    },
+};
+async function main() {
+    const [, , cmd, sub, ...rest] = process.argv;
+    // 子命令路由：在注册表中查找并执行
+    if (cmd && cmd in COMMAND_REGISTRY) {
+        const subMap = COMMAND_REGISTRY[cmd];
+        // sub 命中具名子命令则执行，否则 fallback 到默认（''）
+        const subKey = sub && sub in subMap ? sub : '';
+        const def = subMap[subKey];
+        if (def) {
+            const args = subKey ? rest : (sub ? [sub, ...rest] : []);
+            await def.handler(args);
+            process.exit(0);
+        }
+    }
+    const toolName = cmd;
+    const rawParams = sub ?? '{}';
+    // 无参数时打印帮助（按认证类型过滤工具列表，自动从注册表生成子命令说明）
+    if (!toolName || toolName === '--help' || toolName === '-h') {
+        const authType = (process.env.FEISHU_AUTH_TYPE ?? 'tenant');
+        const subcommands = {};
+        for (const [c, subMap] of Object.entries(COMMAND_REGISTRY)) {
+            for (const [s, def] of Object.entries(subMap)) {
+                subcommands[s ? `${c} ${s}` : c] = def.description;
+            }
+        }
+        process.stdout.write(JSON.stringify({
+            usage: "feishu-mcp-tool <tool-name> '<json-params>'",
+            subcommands,
+            authType,
+            toolsNote: authType === 'tenant'
+                ? 'task/member 工具需 FEISHU_AUTH_TYPE=user 才可用'
+                : '所有工具均可用',
+            tools: listTools(authType),
+        }, null, 2) + '\n');
+        process.exit(0);
+    }
+    // 解析参数
+    let params;
+    try {
+        params = JSON.parse(rawParams);
+    }
+    catch {
+        process.stdout.write(JSON.stringify({ error: `参数解析失败，请提供合法的 JSON 字符串: ${rawParams}` }) + '\n');
+        process.exit(1);
+    }
+    // 调度工具
+    try {
+        const result = await dispatch(toolName, params);
+        // 若工具已返回序列化字符串（如 get_feishu_document_blocks），直接输出避免双重编码
+        process.stdout.write((typeof result === 'string' ? result : JSON.stringify(result)) + '\n');
+        process.exit(0);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message
+            : typeof err === 'object' && err !== null ? JSON.stringify(err)
+                : String(err);
+        process.stdout.write(JSON.stringify({ error: message }) + '\n');
+        process.exit(1);
+    }
+}
+main().catch(() => process.exit(1));

package/dist/manager/sseConnectionManager.js

@@ -48,6 +48,8 @@ export class SSEConnectionManager {
                 }
             }
         }, this.KEEP_ALIVE_INTERVAL_MS);
+        // 不阻止进程在无活跃连接时自然退出（stdio 模式）
+        this.keepAliveIntervalId.unref();
     }
     /**
      * 添加新的SSE连接