@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/channel/plugin.js

@@ -0,0 +1,310 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * ChannelPlugin interface implementation for the Lark/Feishu channel.
+ *
+ * This is the top-level entry point that the OpenClaw plugin system uses to
+ * discover capabilities, resolve accounts, obtain outbound adapters, and
+ * start the inbound event gateway.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.feishuPlugin = void 0;
+const account_id_1 = require("openclaw/plugin-sdk/account-id");
+const channel_status_1 = require("openclaw/plugin-sdk/channel-status");
+const accounts_1 = require("../core/accounts.js");
+const outbound_1 = require("../messaging/outbound/outbound.js");
+const actions_1 = require("../messaging/outbound/actions.js");
+const policy_1 = require("../messaging/inbound/policy.js");
+const lark_client_1 = require("../core/lark-client.js");
+const send_1 = require("../messaging/outbound/send.js");
+const targets_1 = require("../core/targets.js");
+const onboarding_auth_1 = require("../tools/onboarding-auth.js");
+const lark_logger_1 = require("../core/lark-logger.js");
+const config_schema_1 = require("../core/config-schema.js");
+const config_adapter_1 = require("./config-adapter.js");
+const directory_1 = require("./directory.js");
+const pluginLog = (0, lark_logger_1.larkLogger)('channel/plugin');
+/** 状态轮询的探针结果缓存时长（5 分钟）。 */
+const PROBE_CACHE_TTL_MS = 5 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Convert nullable SDK params to optional params for directory functions. */
+function adaptDirectoryParams(params) {
+    return {
+        cfg: params.cfg,
+        query: params.query ?? undefined,
+        limit: params.limit ?? undefined,
+        accountId: params.accountId ?? undefined,
+    };
+}
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+const meta = {
+    id: 'feishu',
+    label: 'Feishu',
+    selectionLabel: 'Lark/Feishu (\u98DE\u4E66)',
+    docsPath: '/channels/feishu',
+    docsLabel: 'feishu',
+    blurb: '\u98DE\u4E66/Lark enterprise messaging.',
+    aliases: ['lark'],
+    order: 70,
+};
+// ---------------------------------------------------------------------------
+// Channel plugin definition
+// ---------------------------------------------------------------------------
+exports.feishuPlugin = {
+    id: 'feishu',
+    meta: {
+        ...meta,
+    },
+    // -------------------------------------------------------------------------
+    // Pairing
+    // -------------------------------------------------------------------------
+    pairing: {
+        idLabel: 'feishuUserId',
+        normalizeAllowEntry: (entry) => entry.replace(/^(feishu|user|open_id):/i, ''),
+        notifyApproval: async ({ cfg, id }) => {
+            const accountId = (0, accounts_1.getDefaultLarkAccountId)(cfg);
+            pluginLog.info('notifyApproval called', { id, accountId });
+            // 1. 发送配对成功消息（保持现有行为）
+            await (0, send_1.sendMessageFeishu)({
+                cfg,
+                to: id,
+                text: channel_status_1.PAIRING_APPROVED_MESSAGE,
+                accountId,
+            });
+            // 2. 触发 onboarding
+            try {
+                await (0, onboarding_auth_1.triggerOnboarding)({ cfg, userOpenId: id, accountId });
+                pluginLog.info('onboarding completed', { id });
+            }
+            catch (err) {
+                pluginLog.warn('onboarding failed', { id, error: String(err) });
+            }
+        },
+    },
+    // -------------------------------------------------------------------------
+    // Capabilities
+    // -------------------------------------------------------------------------
+    capabilities: {
+        chatTypes: ['direct', 'group'],
+        media: true,
+        reactions: true,
+        threads: true,
+        polls: false,
+        nativeCommands: true,
+        blockStreaming: true,
+    },
+    // -------------------------------------------------------------------------
+    // Agent prompt
+    // -------------------------------------------------------------------------
+    agentPrompt: {
+        messageToolHints: () => [
+            '- Feishu targeting: omit `target` to reply to the current conversation (auto-inferred). Explicit targets: `user:open_id` or `chat:chat_id`.',
+            '- Feishu supports interactive cards for rich messages.',
+            '- Feishu reactions use UPPERCASE emoji type names (e.g. `OK`,`THUMBSUP`,`THANKS`,`MUSCLE`,`FINGERHEART`,`APPLAUSE`,`FISTBUMP`,`JIAYI`,`DONE`,`SMILE`,`BLUSH` ), not Unicode emoji characters.',
+            "- Feishu `action=delete`/`action=unsend` only deletes messages sent by the bot. When the user quotes a message and says 'delete this', use the **quoted message's** message_id, not the user's own message_id.",
+        ],
+    },
+    // -------------------------------------------------------------------------
+    // Groups
+    // -------------------------------------------------------------------------
+    groups: {
+        resolveToolPolicy: policy_1.resolveFeishuGroupToolPolicy,
+    },
+    // -------------------------------------------------------------------------
+    // Reload
+    // -------------------------------------------------------------------------
+    reload: { configPrefixes: ['channels.feishu'] },
+    // -------------------------------------------------------------------------
+    // Config schema (JSON Schema)
+    // -------------------------------------------------------------------------
+    configSchema: {
+        schema: config_schema_1.FEISHU_CONFIG_JSON_SCHEMA,
+    },
+    // -------------------------------------------------------------------------
+    // Config adapter
+    // -------------------------------------------------------------------------
+    config: {
+        listAccountIds: (cfg) => (0, accounts_1.getLarkAccountIds)(cfg),
+        resolveAccount: (cfg, accountId) => (0, accounts_1.getLarkAccount)(cfg, accountId),
+        defaultAccountId: (cfg) => (0, accounts_1.getDefaultLarkAccountId)(cfg),
+        setAccountEnabled: ({ cfg, accountId, enabled }) => {
+            return (0, config_adapter_1.setAccountEnabled)(cfg, accountId, enabled);
+        },
+        deleteAccount: ({ cfg, accountId }) => {
+            return (0, config_adapter_1.deleteAccount)(cfg, accountId);
+        },
+        isConfigured: (account) => account.configured,
+        describeAccount: (account) => ({
+            accountId: account.accountId,
+            enabled: account.enabled,
+            configured: account.configured,
+            name: account.name,
+            appId: account.appId,
+            brand: account.brand,
+        }),
+        resolveAllowFrom: ({ cfg, accountId }) => {
+            const account = (0, accounts_1.getLarkAccount)(cfg, accountId);
+            return (account.config?.allowFrom ?? []).map((entry) => String(entry));
+        },
+        formatAllowFrom: ({ allowFrom }) => allowFrom
+            .map((entry) => String(entry).trim())
+            .filter(Boolean)
+            .map((entry) => entry.toLowerCase()),
+    },
+    // -------------------------------------------------------------------------
+    // Security
+    // -------------------------------------------------------------------------
+    security: {
+        collectWarnings: ({ cfg, accountId }) => (0, config_adapter_1.collectFeishuSecurityWarnings)({ cfg, accountId: accountId ?? account_id_1.DEFAULT_ACCOUNT_ID }),
+    },
+    // -------------------------------------------------------------------------
+    // Setup
+    // -------------------------------------------------------------------------
+    setup: {
+        resolveAccountId: () => account_id_1.DEFAULT_ACCOUNT_ID,
+        applyAccountConfig: ({ cfg, accountId }) => {
+            return (0, config_adapter_1.applyAccountConfig)(cfg, accountId, { enabled: true });
+        },
+    },
+    // -------------------------------------------------------------------------
+    // Messaging
+    // -------------------------------------------------------------------------
+    messaging: {
+        normalizeTarget: (raw) => (0, targets_1.normalizeFeishuTarget)(raw) ?? undefined,
+        targetResolver: {
+            looksLikeId: targets_1.looksLikeFeishuId,
+            hint: '<chatId|user:openId|chat:chatId>',
+        },
+    },
+    // -------------------------------------------------------------------------
+    // Directory
+    // -------------------------------------------------------------------------
+    directory: {
+        self: async () => null,
+        listPeers: async (p) => (0, directory_1.listFeishuDirectoryPeers)(adaptDirectoryParams(p)),
+        listGroups: async (p) => (0, directory_1.listFeishuDirectoryGroups)(adaptDirectoryParams(p)),
+        listPeersLive: async (p) => (0, directory_1.listFeishuDirectoryPeersLive)(adaptDirectoryParams(p)),
+        listGroupsLive: async (p) => (0, directory_1.listFeishuDirectoryGroupsLive)(adaptDirectoryParams(p)),
+    },
+    // -------------------------------------------------------------------------
+    // Outbound
+    // -------------------------------------------------------------------------
+    outbound: outbound_1.feishuOutbound,
+    // -------------------------------------------------------------------------
+    // Threading
+    // -------------------------------------------------------------------------
+    threading: {
+        buildToolContext: ({ context, hasRepliedRef }) => ({
+            currentChannelId: (0, targets_1.normalizeFeishuTarget)(context.To ?? '') ?? undefined,
+            currentThreadTs: context.MessageThreadId != null ? String(context.MessageThreadId) : undefined,
+            currentMessageId: context.CurrentMessageId,
+            hasRepliedRef,
+        }),
+    },
+    // -------------------------------------------------------------------------
+    // Actions
+    // -------------------------------------------------------------------------
+    actions: actions_1.feishuMessageActions,
+    // -------------------------------------------------------------------------
+    // Status
+    // -------------------------------------------------------------------------
+    status: {
+        defaultRuntime: {
+            accountId: account_id_1.DEFAULT_ACCOUNT_ID,
+            running: false,
+            lastStartAt: null,
+            lastStopAt: null,
+            lastError: null,
+            port: null,
+        },
+        buildChannelSummary: ({ snapshot }) => ({
+            configured: snapshot.configured ?? false,
+            running: snapshot.running ?? false,
+            lastStartAt: snapshot.lastStartAt ?? null,
+            lastStopAt: snapshot.lastStopAt ?? null,
+            lastError: snapshot.lastError ?? null,
+            port: snapshot.port ?? null,
+            probe: snapshot.probe,
+            lastProbeAt: snapshot.lastProbeAt ?? null,
+        }),
+        probeAccount: async ({ account }) => {
+            return await lark_client_1.LarkClient.fromAccount(account).probe({ maxAgeMs: PROBE_CACHE_TTL_MS });
+        },
+        buildAccountSnapshot: ({ account, runtime, probe }) => ({
+            accountId: account.accountId,
+            enabled: account.enabled,
+            configured: account.configured,
+            name: account.name,
+            appId: account.appId,
+            brand: account.brand,
+            running: runtime?.running ?? false,
+            lastStartAt: runtime?.lastStartAt ?? null,
+            lastStopAt: runtime?.lastStopAt ?? null,
+            lastError: runtime?.lastError ?? null,
+            port: runtime?.port ?? null,
+            probe,
+        }),
+    },
+    // -------------------------------------------------------------------------
+    // Gateway
+    // -------------------------------------------------------------------------
+    gateway: {
+        startAccount: async (ctx) => {
+            const { monitorFeishuProvider } = await Promise.resolve().then(() => __importStar(require('./monitor.js')));
+            const account = (0, accounts_1.getLarkAccount)(ctx.cfg, ctx.accountId);
+            const port = account.config?.webhookPort ?? null;
+            ctx.setStatus({ accountId: ctx.accountId, port });
+            ctx.log?.info(`starting feishu[${ctx.accountId}] (mode: ${account.config?.connectionMode ?? 'websocket'})`);
+            return monitorFeishuProvider({
+                config: ctx.cfg,
+                runtime: ctx.runtime,
+                abortSignal: ctx.abortSignal,
+                accountId: ctx.accountId,
+            });
+        },
+        stopAccount: async (ctx) => {
+            ctx.log?.info(`stopping feishu[${ctx.accountId}]`);
+            await lark_client_1.LarkClient.clearCache(ctx.accountId);
+            ctx.log?.info(`stopped feishu[${ctx.accountId}]`);
+        },
+    },
+};

package/src/channel/probe.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+import { type LarkClientCredentials } from '../core/lark-client';
+import type { FeishuProbeResult } from './types';
+/**
+ * Probe the Feishu bot connection by calling the bot/v3/info API.
+ *
+ * Returns a result indicating whether the bot is reachable and its
+ * basic identity (name, open_id).  Used by onboarding and status
+ * checks to verify credentials before committing them to config.
+ */
+export declare function probeFeishu(credentials?: LarkClientCredentials): Promise<FeishuProbeResult>;

package/src/channel/probe.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.probeFeishu = probeFeishu;
+const lark_client_1 = require("../core/lark-client.js");
+/**
+ * Probe the Feishu bot connection by calling the bot/v3/info API.
+ *
+ * Returns a result indicating whether the bot is reachable and its
+ * basic identity (name, open_id).  Used by onboarding and status
+ * checks to verify credentials before committing them to config.
+ */
+async function probeFeishu(credentials) {
+    if (!credentials?.appId || !credentials?.appSecret) {
+        return {
+            ok: false,
+            error: 'missing credentials (appId, appSecret)',
+        };
+    }
+    return lark_client_1.LarkClient.fromCredentials(credentials).probe();
+}

package/src/channel/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Channel type definitions for the Lark/Feishu channel plugin.
+ */
+import type { ClawdbotConfig, RuntimeEnv } from 'openclaw/plugin-sdk';
+import type { HistoryEntry } from 'openclaw/plugin-sdk/reply-history';
+import type { LarkClient } from '../core/lark-client';
+import type { MessageDedup } from '../messaging/inbound/dedup';
+export type { FeishuProbeResult } from '../core/types';
+export interface MonitorFeishuOpts {
+    config?: ClawdbotConfig;
+    runtime?: RuntimeEnv;
+    abortSignal?: AbortSignal;
+    accountId?: string;
+}
+export interface FeishuDirectoryPeer {
+    kind: 'user';
+    id: string;
+    name?: string;
+}
+export interface FeishuDirectoryGroup {
+    kind: 'group';
+    id: string;
+    name?: string;
+}
+export interface MonitorContext {
+    cfg: ClawdbotConfig;
+    lark: LarkClient;
+    accountId: string;
+    chatHistories: Map<string, HistoryEntry[]>;
+    messageDedup: MessageDedup;
+    runtime?: RuntimeEnv;
+    log: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}

package/src/channel/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Channel type definitions for the Lark/Feishu channel plugin.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/commands/auth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_auth command — 飞书用户权限批量授权命令实现
+ *
+ * 直接复用 onboarding-auth.ts 的 triggerOnboarding() 函数。
+ * 注意：此命令仅限应用 owner 执行（与 onboarding 逻辑一致）
+ */
+import type { OpenClawConfig } from 'openclaw/plugin-sdk';
+import type { FeishuLocale } from './locale';
+/**
+ * 执行飞书用户权限批量授权命令
+ * 直接调用 triggerOnboarding()，包含 owner 检查
+ */
+export declare function runFeishuAuth(config: OpenClawConfig, locale?: FeishuLocale): Promise<string>;
+/**
+ * 运行飞书授权命令，同时生成中英双语结果。
+ * 副作用（triggerOnboarding）只执行一次，结果格式化为双语文本。
+ */
+export declare function runFeishuAuthI18n(config: OpenClawConfig): Promise<Record<FeishuLocale, string>>;

package/src/commands/auth.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_auth command — 飞书用户权限批量授权命令实现
+ *
+ * 直接复用 onboarding-auth.ts 的 triggerOnboarding() 函数。
+ * 注意：此命令仅限应用 owner 执行（与 onboarding 逻辑一致）
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFeishuAuth = runFeishuAuth;
+exports.runFeishuAuthI18n = runFeishuAuthI18n;
+const onboarding_auth_1 = require("../tools/onboarding-auth.js");
+const lark_ticket_1 = require("../core/lark-ticket.js");
+const accounts_1 = require("../core/accounts.js");
+const lark_client_1 = require("../core/lark-client.js");
+const app_scope_checker_1 = require("../core/app-scope-checker.js");
+const token_store_1 = require("../core/token-store.js");
+const tool_scopes_1 = require("../core/tool-scopes.js");
+const owner_policy_1 = require("../core/owner-policy.js");
+const domains_1 = require("../core/domains.js");
+// ---------------------------------------------------------------------------
+// I18n text map
+// ---------------------------------------------------------------------------
+const T = {
+    zh_cn: {
+        noIdentity: '❌ 无法获取用户身份，请在飞书对话中使用此命令',
+        accountIncomplete: (accountId) => `❌ 账号 ${accountId} 配置不完整`,
+        missingSelfManage: (link) => `❌ 应用缺少核心权限 application:application:self_manage，无法查询可授权 scope 列表。\n\n请管理员在飞书开放平台开通此权限后重试：[申请权限](${link})`,
+        ownerOnly: '❌ 此命令仅限应用 owner 执行\n\n如需授权，请联系应用管理员。',
+        missingOfflineAccess: (link) => `❌ 应用缺少核心权限 offline_access，无法查询可授权 scope 列表。\n\n请管理员在飞书开放平台开通此权限后重试：[申请权限](${link})`,
+        noUserScopes: '当前应用未开通任何用户级权限，无需授权。',
+        allAuthorized: (count) => `✅ 您已授权所有可用权限（共 ${count} 个），无需重复授权。`,
+        authSent: '✅ 已发送授权请求',
+    },
+    en_us: {
+        noIdentity: '❌ Unable to identify user. Please use this command in a Feishu conversation.',
+        accountIncomplete: (accountId) => `❌ Account ${accountId} configuration is incomplete`,
+        missingSelfManage: (link) => `❌ App is missing the core permission application:application:self_manage and cannot query available scopes.\n\nPlease ask an admin to grant this permission on the Feishu Open Platform: [Apply](${link})`,
+        ownerOnly: '❌ This command is restricted to the app owner.\n\nPlease contact the app admin for authorization.',
+        missingOfflineAccess: (link) => `❌ App is missing the core permission offline_access and cannot query available scopes.\n\nPlease ask an admin to grant this permission on the Feishu Open Platform: [Apply](${link})`,
+        noUserScopes: 'No user-level permissions are enabled for this app. Authorization is not needed.',
+        allAuthorized: (count) => `✅ You have authorized all available permissions (${count} total). No re-authorization needed.`,
+        authSent: '✅ Authorization request sent',
+    },
+};
+/**
+ * Format an AuthResult into a locale-specific message string.
+ */
+function formatAuthResult(result, locale) {
+    const t = T[locale];
+    switch (result.kind) {
+        case 'no_identity':
+            return t.noIdentity;
+        case 'account_incomplete':
+            return t.accountIncomplete(result.accountId);
+        case 'missing_self_manage':
+            return t.missingSelfManage(result.link);
+        case 'owner_only':
+            return t.ownerOnly;
+        case 'missing_offline_access':
+            return t.missingOfflineAccess(result.link);
+        case 'no_user_scopes':
+            return t.noUserScopes;
+        case 'all_authorized':
+            return t.allAuthorized(result.count);
+        case 'auth_sent':
+            return t.authSent;
+    }
+}
+// ---------------------------------------------------------------------------
+// Core logic (executes side-effects exactly once)
+// ---------------------------------------------------------------------------
+/**
+ * Execute the auth command logic, including side-effects (triggerOnboarding).
+ * Returns a discriminated result that can be formatted into any locale.
+ */
+async function executeFeishuAuth(config) {
+    const ticket = (0, lark_ticket_1.getTicket)();
+    const senderOpenId = ticket?.senderOpenId;
+    if (!senderOpenId) {
+        return { kind: 'no_identity' };
+    }
+    // 提前检查 owner 身份，给出明确提示
+    const acct = (0, accounts_1.getLarkAccount)(config, ticket.accountId);
+    if (!acct.configured) {
+        return { kind: 'account_incomplete', accountId: ticket.accountId };
+    }
+    const sdk = lark_client_1.LarkClient.fromAccount(acct).sdk;
+    const { appId } = acct;
+    const openDomain = (0, domains_1.openPlatformDomain)(acct.brand);
+    try {
+        await (0, app_scope_checker_1.getAppInfo)(sdk, appId);
+    }
+    catch {
+        const link = `${openDomain}/app/${appId}/auth?q=application:application:self_manage&op_from=feishu-openclaw&token_type=tenant`;
+        return { kind: 'missing_self_manage', link };
+    }
+    // Owner 检查（fail-close: 授权命令安全优先）
+    try {
+        await (0, owner_policy_1.assertOwnerAccessStrict)(acct, sdk, senderOpenId);
+    }
+    catch (err) {
+        if (err instanceof owner_policy_1.OwnerAccessDeniedError) {
+            return { kind: 'owner_only' };
+        }
+        throw err;
+    }
+    // 预检：是否还有未授权的 scope
+    let appScopes;
+    try {
+        appScopes = await (0, app_scope_checker_1.getAppGrantedScopes)(sdk, appId, 'user');
+    }
+    catch {
+        const link = `${openDomain}/app/${appId}/auth?q=application:application:self_manage&op_from=feishu-openclaw&token_type=tenant`;
+        return { kind: 'missing_self_manage', link };
+    }
+    // offline_access 预检 — OAuth 必须的前提权限
+    const allScopes = await (0, app_scope_checker_1.getAppGrantedScopes)(sdk, appId);
+    if (allScopes.length > 0 && !allScopes.includes('offline_access')) {
+        const link = `${openDomain}/app/${appId}/auth?q=offline_access&op_from=feishu-openclaw&token_type=user`;
+        return { kind: 'missing_offline_access', link };
+    }
+    appScopes = (0, tool_scopes_1.filterSensitiveScopes)(appScopes);
+    if (appScopes.length === 0) {
+        return { kind: 'no_user_scopes' };
+    }
+    const existing = await (0, token_store_1.getStoredToken)(appId, senderOpenId);
+    const tokenValid = existing && (0, token_store_1.tokenStatus)(existing) !== 'expired';
+    const grantedScopes = new Set(tokenValid ? (existing.scope?.split(/\s+/).filter(Boolean) ?? []) : []);
+    const missingScopes = appScopes.filter((s) => !grantedScopes.has(s));
+    if (missingScopes.length === 0) {
+        return { kind: 'all_authorized', count: appScopes.length };
+    }
+    // 调用 triggerOnboarding 执行批量授权（副作用，只执行一次）
+    await (0, onboarding_auth_1.triggerOnboarding)({
+        cfg: config,
+        userOpenId: senderOpenId,
+        accountId: ticket.accountId,
+    });
+    return { kind: 'auth_sent' };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * 执行飞书用户权限批量授权命令
+ * 直接调用 triggerOnboarding()，包含 owner 检查
+ */
+async function runFeishuAuth(config, locale = 'zh_cn') {
+    const result = await executeFeishuAuth(config);
+    return formatAuthResult(result, locale);
+}
+/**
+ * 运行飞书授权命令，同时生成中英双语结果。
+ * 副作用（triggerOnboarding）只执行一次，结果格式化为双语文本。
+ */
+async function runFeishuAuthI18n(config) {
+    const result = await executeFeishuAuth(config);
+    return {
+        zh_cn: formatAuthResult(result, 'zh_cn'),
+        en_us: formatAuthResult(result, 'en_us'),
+    };
+}

package/src/commands/diagnose.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Diagnostic module for the Lark/Feishu plugin.
+ *
+ * Collects environment info, account configuration, API connectivity,
+ * app permissions, tool registration state, and recent error logs into
+ * a structured report that users can share with developers for
+ * remote troubleshooting.
+ */
+import type { OpenClawConfig } from 'openclaw/plugin-sdk';
+interface DiagLogger {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+type CheckStatus = 'pass' | 'warn' | 'fail' | 'skip';
+interface DiagCheckResult {
+    name: string;
+    status: CheckStatus;
+    message: string;
+    details?: string;
+}
+interface AccountDiagResult {
+    accountId: string;
+    name?: string;
+    enabled: boolean;
+    configured: boolean;
+    appId?: string;
+    brand: string;
+    checks: DiagCheckResult[];
+}
+interface DiagReport {
+    timestamp: string;
+    environment: {
+        nodeVersion: string;
+        platform: string;
+        arch: string;
+        pluginVersion: string;
+    };
+    accounts: AccountDiagResult[];
+    toolsRegistered: string[];
+    recentErrors: string[];
+    overallStatus: 'healthy' | 'degraded' | 'unhealthy';
+    checks: DiagCheckResult[];
+}
+export declare function runDiagnosis(params: {
+    config: OpenClawConfig;
+    logger?: DiagLogger;
+}): Promise<DiagReport>;
+export declare function formatDiagReportText(report: DiagReport): string;
+/**
+ * Extract all log lines tagged with a specific message_id from gateway.log.
+ *
+ * Scans the last 1MB of the log file for lines containing `[msg:{messageId}]`.
+ * Returns matching lines in chronological order.
+ */
+export declare function traceByMessageId(messageId: string): Promise<string[]>;
+/**
+ * Format trace output for CLI display.
+ */
+export declare function formatTraceOutput(lines: string[], messageId: string): string;
+/**
+ * Analyze trace log lines and produce a structured CLI report.
+ */
+export declare function analyzeTrace(lines: string[], _messageId: string): string;
+export declare function formatDiagReportCli(report: DiagReport): string;
+export {};