@wu529778790/open-im 1.9.4-beta.12 → 1.9.4-beta.13

package/dist/feishu/client.d.ts

@@ -1,5 +1,12 @@
 import { Client } from '@larksuiteoapi/node-sdk';
 import type { Config } from '../config.js';
 export declare function getClient(): Client;
+/** 获取当前飞书应用 appId（用于构建权限链接等） */
+export declare function getAppId(): string;
+/**
+ * 格式化飞书初始化错误（供 index.ts 平台注册使用）
+ * 参照 DingTalk 的 formatDingTalkInitError 模式
+ */
+export declare function formatFeishuInitError(err: unknown): string;
 export declare function initFeishu(config: Config, eventHandler: (data: unknown) => Promise<void | Record<string, unknown>>): Promise<void>;
 export declare function stopFeishu(): void;

package/dist/feishu/client.js

@@ -1,5 +1,6 @@
 import { Client, WSClient, EventDispatcher, LoggerLevel } from '@larksuiteoapi/node-sdk';
 import { createLogger } from '../logger.js';
+import { isPermissionError, logPermissionGuide } from './permission.js';
 const log = createLogger('Feishu');
 let client = null;
 let wsClient = null;
@@ -8,6 +9,30 @@ export function getClient() {
         throw new Error('Feishu client not initialized');
     return client;
 }
+/** 获取当前飞书应用 appId（用于构建权限链接等） */
+export function getAppId() {
+    if (!client)
+        throw new Error('Feishu client not initialized');
+    return client.appId;
+}
+/**
+ * 格式化飞书初始化错误（供 index.ts 平台注册使用）
+ * 参照 DingTalk 的 formatDingTalkInitError 模式
+ */
+export function formatFeishuInitError(err) {
+    if (isPermissionError(err)) {
+        const appId = client?.appId;
+        const permUrl = appId ? `https://open.feishu.cn/app/${appId}/permission` : 'https://open.feishu.cn/app';
+        return [
+            '飞书应用权限不足。',
+            `请前往开通权限: ${permUrl}`,
+            '需要: im:message, im:message:send_as_bot, im:resource, im:chat',
+        ].join(' ');
+    }
+    if (err instanceof Error)
+        return err.message;
+    return String(err).slice(0, 200);
+}
 export async function initFeishu(config, eventHandler) {
     if (!config.feishuAppId || !config.feishuAppSecret) {
         throw new Error('Feishu app_id and app_secret are required');
@@ -70,6 +95,30 @@ export async function initFeishu(config, eventHandler) {
         log.error('Failed to start Feishu WebSocket:', err);
         throw err;
     }
+    // 启动时校验凭证有效性并输出权限要求提示
+    try {
+        const tokenResp = await client.auth.tenantAccessToken.internal({
+            data: {
+                app_id: config.feishuAppId,
+                app_secret: config.feishuAppSecret,
+            },
+        });
+        if (tokenResp.code !== 0 || !tokenResp.data) {
+            throw new Error(`Feishu credentials invalid: ${tokenResp.msg} (code: ${tokenResp.code})`);
+        }
+        log.info('Feishu credentials validated successfully');
+    }
+    catch (err) {
+        if (isPermissionError(err)) {
+            log.error('飞书应用凭证校验失败 — 权限不足');
+        }
+        else {
+            log.error('飞书应用凭证校验失败:', err instanceof Error ? err.message : err);
+        }
+        throw err;
+    }
+    // 输出权限要求提示（连接成功后）
+    logPermissionGuide(config.feishuAppId);
     log.info('Feishu client initialized');
 }
 export function stopFeishu() {

package/dist/feishu/event-handler.js

@@ -11,102 +11,8 @@ import { buildProgressNote } from '../shared/message-note.js';
 import { createPlatformEventContext } from '../platform/create-event-context.js';
 import { createPlatformAIRequestHandler } from '../platform/handle-ai-request.js';
 import { handleTextFlow } from '../platform/handle-text-flow.js';
+import { isPermissionError, handlePermissionError } from './permission.js';
 const log = createLogger('FeishuHandler');
-/**
-/**
- *
- 从异常中提取飞书 API 错误码
- */
-function extractFeishuErrorCode(err) {
-    const e = err;
-    if (e?.response?.data?.code)
-        return e.response.data.code;
-    if (e?.code)
-        return e.code;
-    return undefined;
-}
-/**
- * 根据错误码判断是否为权限不足
- */
-function isPermissionError(err) {
-    const code = extractFeishuErrorCode(err);
-    if (!code) {
-        // 非标准错误：检查 message 中是否包含权限关键词
-        const msg = err?.message ?? String(err);
-        return /permission|权限|scope|not authorized|no access|forbidden/i.test(msg);
-    }
-    // 飞书常见权限错误码
-    return [
-        99991400, // 权限不足
-        99991401, // 没有API权限
-        99991663, // 应用未获取 scope
-        99991672, // 应用未开通相关能力
-        99991670, // 应用未上架/未授权
-        99991668, // 应用可见性限制
-    ].includes(code);
-}
-/**
- * 构建飞书权限配置指引消息
- */
-function buildPermissionGuideMessage(err) {
-    const code = extractFeishuErrorCode(err);
-    const codeHint = code ? ` (错误码: ${code})` : '';
-    return [
-        '⚠️ **飞书应用权限不足，无法发送消息**' + codeHint,
-        '',
-        '请按以下步骤开通所需权限：',
-        '',
-        '**1. 进入飞书开放平台**',
-        '👉 https://open.feishu.cn/app',
-        '',
-        '**2. 找到你的应用，进入「权限管理」**',
-        '',
-        '**3. 开通以下权限（搜索权限名称添加）：**',
-        '• `im:message` — 获取与发送单聊、群组消息',
-        '• `im:message:send_as_bot` — 以应用身份发消息',
-        '• `im:resource` — 获取与上传图片或文件资源',
-        '• `im:chat` — 获取群组信息',
-        '',
-        '**4. 如需使用卡片打字机效果，还需开通：**',
-        '• `cardkit:card` — CardKit 卡片管理',
-        '',
-        '**5. 发布版本**',
-        '权限修改后需点击「创建版本」→「发布」，管理员审批后生效。',
-        '',
-        '📖 详细文档：https://open.feishu.cn/document/ukTMukTMukTM/ucTM5YjL3ETO04yNxkDN',
-    ].join('\n');
-}
-/**
- * 发送权限错误提示，依次尝试：卡片 → 纯文本 → open_id
- */
-async function sendPermissionFallback(chatId, guide) {
-    // 1. 先尝试 sendTextReply（发卡片消息）
-    try {
-        await sendTextReply(chatId, guide);
-        return;
-    }
-    catch (err) {
-        log.warn('Card-based reply failed, falling back to plain text:', err);
-    }
-    // 2. 降级为纯文本消息
-    try {
-        const client = (await import('./client.js')).getClient();
-        const plainGuide = guide.replace(/\*\*/g, '').replace(/`/g, '');
-        await client.im.message.create({
-            data: {
-                receive_id: chatId,
-                msg_type: 'text',
-                content: JSON.stringify({ text: plainGuide }),
-            },
-            params: { receive_id_type: 'chat_id' },
-        });
-        return;
-    }
-    catch (err) {
-        log.warn('Plain text reply also failed:', err);
-    }
-    log.error('All fallback methods failed to send permission guide');
-}
 async function downloadFeishuMessageResource(client, messageId, fileKey, type, options) {
     const targetPath = createMediaTargetPath(options?.fallbackExtension ?? 'bin', options?.basenameHint ?? fileKey);
     const response = await client.im.messageResource.get({
@@ -152,12 +58,9 @@ export function setupFeishuHandlers(config, sessionManager) {
                         continue;
                     }
                     log.error(`Failed to send thinking card after ${attempt} attempts:`, err);
-                    // Detect permission errors
+                    // 检测权限错误并输出友好提示
                     if (isPermissionError(err)) {
-                        const guide = buildPermissionGuideMessage(err);
-                        await sendPermissionFallback(chatId, guide).catch((e) => {
-                            log.warn('Permission fallback send failed:', e);
-                        });
+                        handlePermissionError(err, chatId);
                     }
                     throw err;
                 }

package/dist/feishu/message-sender.js

@@ -8,6 +8,7 @@ import { getAIToolDisplayName } from '../shared/utils.js';
 import { buildMessageTitle, OPEN_IM_SYSTEM_TITLE } from '../shared/message-title.js';
 import { buildTextNote } from '../shared/message-note.js';
 import { createCard, enableStreaming, sendCardMessage, streamContent as cardkitStreamContent, updateCardFull, markCompleted, disableStreaming, destroySession, } from './cardkit-manager.js';
+import { isPermissionError, handlePermissionError } from './permission.js';
 const log = createLogger('FeishuSender');
 const STATUS_CONFIG = {
     thinking: { icon: '🔵', template: 'blue', title: '思考中' },
@@ -101,6 +102,9 @@ export async function sendThinkingMessage(chatId, replyToMessageId, toolId = 'cl
     }
     catch (err) {
         log.error('Failed to send thinking message:', err);
+        if (isPermissionError(err)) {
+            handlePermissionError(err, chatId);
+        }
         throw err;
     }
 }
@@ -137,14 +141,23 @@ export async function sendFinalCards(chatId, _messageId, cardId, fullContent, no
     for (let i = 1; i < parts.length; i++) {
         const overflowContent = `${parts[i]}\n\n_*(续 ${i + 1}/${parts.length})*_`;
         const overflowCard = createFeishuCard(getToolTitle(toolId, 'done'), overflowContent, 'done', note);
-        await client.im.message.create({
-            data: {
-                receive_id: chatId,
-                msg_type: 'interactive',
-                content: overflowCard,
-            },
-            params: { receive_id_type: 'chat_id' },
-        });
+        try {
+            await client.im.message.create({
+                data: {
+                    receive_id: chatId,
+                    msg_type: 'interactive',
+                    content: overflowCard,
+                },
+                params: { receive_id_type: 'chat_id' },
+            });
+        }
+        catch (err) {
+            if (isPermissionError(err)) {
+                handlePermissionError(err, chatId);
+                break;
+            }
+            log.error(`Failed to send overflow card ${i + 1}:`, err);
+        }
     }
     destroySession(cardId);
 }
@@ -285,6 +298,10 @@ export async function sendFinalMessages(chatId, messageId, fullContent, note, to
             });
         }
         catch (err) {
+            if (isPermissionError(err)) {
+                handlePermissionError(err, chatId);
+                break;
+            }
             log.error(`Failed to send part ${i + 1}:`, err);
         }
     }
@@ -303,7 +320,12 @@ export async function sendTextReply(chatId, text) {
         });
     }
     catch (err) {
-        log.error('Failed to send text:', err);
+        if (isPermissionError(err)) {
+            handlePermissionError(err, chatId);
+        }
+        else {
+            log.error('Failed to send text:', err);
+        }
     }
 }
 /** 使用 open_id 发送（私聊时 context 可能只有 open_id） */
@@ -321,7 +343,12 @@ export async function sendTextReplyByOpenId(openId, text) {
         });
     }
     catch (err) {
-        log.error('Failed to send text by open_id:', err);
+        if (isPermissionError(err)) {
+            handlePermissionError(err);
+        }
+        else {
+            log.error('Failed to send text by open_id:', err);
+        }
     }
 }
 export async function sendImageReply(chatId, imagePath) {
@@ -360,7 +387,12 @@ export async function sendImageReply(chatId, imagePath) {
         });
     }
     catch (err) {
-        log.error('Failed to send image:', err);
+        if (isPermissionError(err)) {
+            handlePermissionError(err, chatId);
+        }
+        else {
+            log.error('Failed to send image:', err);
+        }
     }
 }
 export function startTypingLoop(_chatId) {

package/dist/feishu/permission.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 飞书权限检测与友好提示
+ *
+ * 统一管理权限错误码、提示消息构建、控制台输出。
+ * 所有飞书发送函数遇到错误时应通过此模块检测权限问题。
+ */
+/**
+ * 从异常中提取飞书 API 错误码
+ */
+export declare function extractFeishuErrorCode(err: unknown): number | undefined;
+/**
+ * 根据错误码判断是否为权限不足
+ */
+export declare function isPermissionError(err: unknown): boolean;
+/**
+ * 构建飞书应用权限设置页直达链接
+ */
+export declare function buildPermissionUrl(appId: string): string;
+/**
+ * 构建飞书开放平台应用列表页链接
+ */
+export declare function buildAppListUrl(): string;
+/**
+ * 构建飞书卡片用的权限指引消息（lark_md 格式）
+ */
+export declare function buildPermissionGuideMessage(err: unknown, appId?: string): string;
+/**
+ * 启动时输出权限要求提示（仅输出一次）
+ */
+export declare function logPermissionGuide(appId: string): void;
+/**
+ * 统一权限错误处理入口。
+ * 始终输出到控制台（保证可见），尽力尝试通过飞书 API 发送提示。
+ */
+export declare function handlePermissionError(err: unknown, chatId?: string): void;

package/dist/feishu/permission.js

@@ -0,0 +1,178 @@
+/**
+ * 飞书权限检测与友好提示
+ *
+ * 统一管理权限错误码、提示消息构建、控制台输出。
+ * 所有飞书发送函数遇到错误时应通过此模块检测权限问题。
+ */
+import { createLogger } from '../logger.js';
+const log = createLogger('FeishuPerm');
+// ── 权限错误码 ──
+const PERMISSION_ERROR_CODES = [
+    99991400, // 权限不足
+    99991401, // 没有API权限
+    99991663, // 应用未获取 scope
+    99991672, // 应用未开通相关能力
+    99991670, // 应用未上架/未授权
+    99991668, // 应用可见性限制
+];
+const REQUIRED_SCOPES = [
+    { scope: 'im:message', label: '获取与发送单聊、群组消息' },
+    { scope: 'im:message:send_as_bot', label: '以应用身份发消息' },
+    { scope: 'im:resource', label: '获取与上传图片或文件资源' },
+    { scope: 'im:chat', label: '获取群组信息' },
+];
+const OPTIONAL_SCOPES = [
+    { scope: 'cardkit:card', label: 'CardKit 卡片管理（打字机效果）' },
+];
+/**
+ * 从异常中提取飞书 API 错误码
+ */
+export function extractFeishuErrorCode(err) {
+    const e = err;
+    if (e?.response?.data?.code)
+        return e.response.data.code;
+    if (e?.code)
+        return e.code;
+    return undefined;
+}
+/**
+ * 根据错误码判断是否为权限不足
+ */
+export function isPermissionError(err) {
+    const code = extractFeishuErrorCode(err);
+    if (!code) {
+        const msg = err?.message ?? String(err);
+        return /permission|权限|scope|not authorized|no access|forbidden/i.test(msg);
+    }
+    return PERMISSION_ERROR_CODES.includes(code);
+}
+// ── 权限直达链接 ──
+/**
+ * 构建飞书应用权限设置页直达链接
+ */
+export function buildPermissionUrl(appId) {
+    return `https://open.feishu.cn/app/${appId}/permission`;
+}
+/**
+ * 构建飞书开放平台应用列表页链接
+ */
+export function buildAppListUrl() {
+    return 'https://open.feishu.cn/app';
+}
+// ── 消息构建 ──
+/**
+ * 构建飞书卡片用的权限指引消息（lark_md 格式）
+ */
+export function buildPermissionGuideMessage(err, appId) {
+    const code = extractFeishuErrorCode(err);
+    const codeHint = code ? ` (错误码: ${code})` : '';
+    const lines = [
+        '⚠️ **飞书应用权限不足，无法发送消息**' + codeHint,
+        '',
+        '请按以下步骤开通所需权限：',
+        '',
+        '**1. 进入飞书开放平台**',
+        '👉 https://open.feishu.cn/app',
+    ];
+    if (appId) {
+        lines.push('', `**2. 进入你的应用权限管理页面**`, `👉 [点击直接打开](${buildPermissionUrl(appId)})`);
+        lines.push('', '**3. 搜索并添加以下权限：**');
+    }
+    else {
+        lines.push('', '**2. 找到你的应用，进入「权限管理」**');
+        lines.push('', '**3. 开通以下权限（搜索权限名称添加）：**');
+    }
+    for (const s of REQUIRED_SCOPES) {
+        lines.push(`• \`${s.scope}\` — ${s.label}`);
+    }
+    lines.push('', '**4. 如需使用卡片打字机效果，还需开通：**');
+    for (const s of OPTIONAL_SCOPES) {
+        lines.push(`• \`${s.scope}\` — ${s.label}`);
+    }
+    lines.push('', '**5. 发布版本**', '权限修改后需点击「创建版本」→「发布」，管理员审批后生效。');
+    return lines.join('\n');
+}
+// ── 控制台输出 ──
+/**
+ * 启动时输出权限要求提示（仅输出一次）
+ */
+export function logPermissionGuide(appId) {
+    const permUrl = buildPermissionUrl(appId);
+    log.info('─── 飞书权限配置 ───');
+    log.info(`权限设置页: ${permUrl}`);
+    log.info('必需权限:');
+    for (const s of REQUIRED_SCOPES) {
+        log.info(`  · ${s.scope} — ${s.label}`);
+    }
+    log.info('可选权限:');
+    for (const s of OPTIONAL_SCOPES) {
+        log.info(`  · ${s.scope} — ${s.label}`);
+    }
+    log.info('权限修改后需发布版本，管理员审批后生效。');
+    log.info('───────────────────');
+}
+// ── 统一错误处理 ──
+let lastPermissionLogTime = 0;
+const PERMISSION_LOG_COOLDOWN_MS = 60_000; // 60 秒内不重复输出
+/**
+ * 统一权限错误处理入口。
+ * 始终输出到控制台（保证可见），尽力尝试通过飞书 API 发送提示。
+ */
+export function handlePermissionError(err, chatId) {
+    const now = Date.now();
+    const silenced = now - lastPermissionLogTime < PERMISSION_LOG_COOLDOWN_MS;
+    if (!silenced) {
+        lastPermissionLogTime = now;
+        const code = extractFeishuErrorCode(err);
+        const codeHint = code ? ` (错误码: ${code})` : '';
+        log.error(`飞书权限不足${codeHint}，无法发送消息。`);
+        // 动态 import 避免循环依赖
+        import('./client.js').then(({ getAppId }) => {
+            const appId = getAppId();
+            log.error(`请前往开通权限: ${buildPermissionUrl(appId)}`);
+        }).catch(() => {
+            log.error(`请前往开通权限: ${buildAppListUrl()}`);
+        });
+    }
+    // Best-effort: 尝试通过飞书 API 发送权限指引
+    if (chatId) {
+        sendPermissionFallback(chatId, err).catch(() => {
+            // 预期会失败（权限不足本身就是根因），log 已经输出过了
+        });
+    }
+}
+/**
+ * 尝试通过飞书 API 发送权限指引消息（降级链：卡片 → 纯文本）
+ */
+async function sendPermissionFallback(chatId, err) {
+    // 动态 import 避免循环依赖
+    const { sendTextReply } = await import('./message-sender.js');
+    const { getAppId } = await import('./client.js');
+    const guide = buildPermissionGuideMessage(err, getAppId());
+    // 1. 尝试卡片消息
+    try {
+        await sendTextReply(chatId, guide);
+        return;
+    }
+    catch {
+        // 降级
+    }
+    // 2. 尝试纯文本消息
+    try {
+        const { getClient } = await import('./client.js');
+        const client = getClient();
+        const plainGuide = guide.replace(/\*\*/g, '').replace(/`/g, '');
+        await client.im.message.create({
+            data: {
+                receive_id: chatId,
+                msg_type: 'text',
+                content: JSON.stringify({ text: plainGuide }),
+            },
+            params: { receive_id_type: 'chat_id' },
+        });
+        return;
+    }
+    catch {
+        // 全部失败，控制台已输出
+    }
+}

package/dist/index.js

@@ -10,7 +10,7 @@ export { needsSetup, runInteractiveSetup };
 import { initTelegram, stopTelegram } from "./telegram/client.js";
 import { setupTelegramHandlers } from "./telegram/event-handler.js";
 import { sendTextReply as sendTelegramTextReply } from "./telegram/message-sender.js";
-import { initFeishu, stopFeishu } from "./feishu/client.js";
+import { initFeishu, stopFeishu, formatFeishuInitError } from "./feishu/client.js";
 import { setupFeishuHandlers } from "./feishu/event-handler.js";
 import { sendTextReply as sendFeishuTextReply } from "./feishu/message-sender.js";
 import { initQQ, stopQQ } from "./qq/client.js";
@@ -52,6 +52,7 @@ const PLATFORM_MODULES = {
         },
         stop: () => stopFeishu(),
         sendNotification: (chatId, msg) => sendFeishuTextReply(chatId, msg),
+        formatError: (err) => formatFeishuInitError(err),
     },
     qq: {
         init: async (config, sessionManager) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wu529778790/open-im",
-  "version": "1.9.4-beta.12",
+  "version": "1.9.4-beta.13",
   "description": "Multi-platform IM bridge for AI CLI tools (Claude, Codex, CodeBuddy)",
   "type": "module",
   "main": "dist/index.js",