@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/commands/index.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Register all chat commands (/feishu_diagnose, /feishu_doctor, /feishu_auth, /feishu).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFeishuStart = runFeishuStart;
+exports.runFeishuStartI18n = runFeishuStartI18n;
+exports.getFeishuHelp = getFeishuHelp;
+exports.getFeishuHelpI18n = getFeishuHelpI18n;
+exports.registerCommands = registerCommands;
+const version_1 = require("../core/version.js");
+const diagnose_1 = require("./diagnose.js");
+const doctor_1 = require("./doctor.js");
+const auth_1 = require("./auth.js");
+// ---------------------------------------------------------------------------
+// I18n text map for /feishu start, help, and error messages
+// ---------------------------------------------------------------------------
+const T = {
+    zh_cn: {
+        legacyNotDisabled: '❌ 检测到旧版插件未禁用。\n' +
+            '👉 请依次运行命令：\n' +
+            '```\n' +
+            'openclaw config set plugins.entries.feishu.enabled false --json\n' +
+            'openclaw gateway restart\n' +
+            '```',
+        toolsProfileWarn: (profile) => `⚠️ 工具 Profile 当前为 \`${profile}\`，飞书工具可能无法加载。请检查配置是否正确。\n`,
+        startFailed: (details) => `❌ 飞书 OpenClaw 插件启动失败：\n\n${details}`,
+        startWithWarnings: (version, details) => `⚠️ 飞书 OpenClaw 插件已启动 v${version}（存在警告）\n\n${details}`,
+        startOk: (version) => `✅ 飞书 OpenClaw 插件已启动 v${version}`,
+        helpTitle: (version) => `飞书OpenClaw插件 v${version}`,
+        helpUsage: '用法：',
+        helpStart: '/feishu start - 校验插件配置',
+        helpAuth: '/feishu auth - 批量授权用户权限',
+        helpDoctor: '/feishu doctor - 运行诊断',
+        helpHelp: '/feishu help - 显示此帮助',
+        diagFailed: (msg) => `诊断执行失败: ${msg}`,
+        authFailed: (msg) => `授权执行失败: ${msg}`,
+        execFailed: (msg) => `执行失败: ${msg}`,
+    },
+    en_us: {
+        legacyNotDisabled: '❌ Legacy plugin is not disabled.\n' +
+            '👉 Please run the following commands:\n' +
+            '```\n' +
+            'openclaw config set plugins.entries.feishu.enabled false --json\n' +
+            'openclaw gateway restart\n' +
+            '```',
+        toolsProfileWarn: (profile) => `⚠️ Tools profile is currently set to \`${profile}\`. Feishu tools may not load properly. Please check your configuration.\n`,
+        startFailed: (details) => `❌ Feishu OpenClaw plugin failed to start:\n\n${details}`,
+        startWithWarnings: (version, details) => `⚠️ Feishu OpenClaw plugin started v${version} (with warnings)\n\n${details}`,
+        startOk: (version) => `✅ Feishu OpenClaw plugin started v${version}`,
+        helpTitle: (version) => `Feishu OpenClaw Plugin v${version}`,
+        helpUsage: 'Usage:',
+        helpStart: '/feishu start - Validate plugin configuration',
+        helpAuth: '/feishu auth - Batch authorize user permissions',
+        helpDoctor: '/feishu doctor - Run diagnostics',
+        helpHelp: '/feishu help - Show this help',
+        diagFailed: (msg) => `Diagnostics failed: ${msg}`,
+        authFailed: (msg) => `Authorization failed: ${msg}`,
+        execFailed: (msg) => `Execution failed: ${msg}`,
+    },
+};
+// ---------------------------------------------------------------------------
+// Exported i18n functions
+// ---------------------------------------------------------------------------
+/**
+ * 运行 /feishu start 校验，返回 Markdown 格式结果。
+ */
+function runFeishuStart(config, locale = 'zh_cn') {
+    const t = T[locale];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cfg = config;
+    const errors = [];
+    const warnings = [];
+    // 检查旧版插件是否已禁用 (error)
+    const feishuEntry = cfg.plugins?.entries?.feishu;
+    if (feishuEntry && feishuEntry.enabled !== false) {
+        errors.push(t.legacyNotDisabled);
+    }
+    // 检查 tools.profile (warning)
+    const profile = cfg.tools?.profile;
+    const incompleteProfiles = new Set(['minimal', 'coding', 'messaging']);
+    if (profile && incompleteProfiles.has(profile)) {
+        warnings.push(t.toolsProfileWarn(profile));
+    }
+    if (errors.length > 0) {
+        const all = [...errors, ...warnings];
+        return t.startFailed(all.join('\n\n'));
+    }
+    if (warnings.length > 0) {
+        return t.startWithWarnings((0, version_1.getPluginVersion)(), warnings.join('\n\n'));
+    }
+    return t.startOk((0, version_1.getPluginVersion)());
+}
+/**
+ * 运行 /feishu start，同时生成中英双语结果。
+ */
+function runFeishuStartI18n(config) {
+    return {
+        zh_cn: runFeishuStart(config, 'zh_cn'),
+        en_us: runFeishuStart(config, 'en_us'),
+    };
+}
+/**
+ * 生成 /feishu help 帮助文本。
+ */
+function getFeishuHelp(locale = 'zh_cn') {
+    const t = T[locale];
+    return (`${t.helpTitle((0, version_1.getPluginVersion)())}\n\n` +
+        `${t.helpUsage}\n` +
+        `  ${t.helpStart}\n` +
+        `  ${t.helpAuth}\n` +
+        `  ${t.helpDoctor}\n` +
+        `  ${t.helpHelp}`);
+}
+/**
+ * 生成 /feishu help，同时生成中英双语结果。
+ */
+function getFeishuHelpI18n() {
+    return {
+        zh_cn: getFeishuHelp('zh_cn'),
+        en_us: getFeishuHelp('en_us'),
+    };
+}
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+function registerCommands(api) {
+    // /feishu_diagnose
+    api.registerCommand({
+        name: 'feishu_diagnose',
+        description: 'Run Feishu plugin diagnostics to check config, connectivity, and permissions',
+        acceptsArgs: false,
+        requireAuth: true,
+        async handler(ctx) {
+            try {
+                const report = await (0, diagnose_1.runDiagnosis)({ config: ctx.config });
+                return { text: (0, diagnose_1.formatDiagReportText)(report) };
+            }
+            catch (err) {
+                return {
+                    text: T.zh_cn.diagFailed(err instanceof Error ? err.message : String(err)),
+                };
+            }
+        },
+    });
+    // /feishu_doctor
+    api.registerCommand({
+        name: 'feishu_doctor',
+        description: 'Run Feishu plugin diagnostics',
+        acceptsArgs: false,
+        requireAuth: true,
+        async handler(ctx) {
+            try {
+                const markdown = await (0, doctor_1.runFeishuDoctor)(ctx.config, ctx.accountId);
+                return { text: markdown };
+            }
+            catch (err) {
+                return {
+                    text: T.zh_cn.diagFailed(err instanceof Error ? err.message : String(err)),
+                };
+            }
+        },
+    });
+    // /feishu_auth
+    api.registerCommand({
+        name: 'feishu_auth',
+        description: 'Batch authorize user permissions for Feishu',
+        acceptsArgs: false,
+        requireAuth: true,
+        async handler(ctx) {
+            try {
+                const result = await (0, auth_1.runFeishuAuth)(ctx.config);
+                return { text: result };
+            }
+            catch (err) {
+                return {
+                    text: T.zh_cn.authFailed(err instanceof Error ? err.message : String(err)),
+                };
+            }
+        },
+    });
+    // /feishu (统一入口，支持子命令)
+    api.registerCommand({
+        name: 'feishu',
+        description: 'Feishu plugin commands (subcommands: auth, doctor, start)',
+        acceptsArgs: true,
+        requireAuth: true,
+        async handler(ctx) {
+            const args = ctx.args?.trim().split(/\s+/) || [];
+            const subcommand = args[0]?.toLowerCase();
+            try {
+                // /feishu auth 或 /feishu onboarding
+                if (subcommand === 'auth' || subcommand === 'onboarding') {
+                    const result = await (0, auth_1.runFeishuAuth)(ctx.config);
+                    return { text: result };
+                }
+                // /feishu doctor
+                if (subcommand === 'doctor') {
+                    const markdown = await (0, doctor_1.runFeishuDoctor)(ctx.config, ctx.accountId);
+                    return { text: markdown };
+                }
+                // /feishu start
+                if (subcommand === 'start') {
+                    return { text: runFeishuStart(ctx.config) };
+                }
+                // /feishu help 或无效子命令或无参数
+                return { text: getFeishuHelp() };
+            }
+            catch (err) {
+                return {
+                    text: T.zh_cn.execFailed(err instanceof Error ? err.message : String(err)),
+                };
+            }
+        },
+    });
+}

package/src/commands/locale.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared locale type for feishu command i18n.
+ */
+export type FeishuLocale = 'zh_cn' | 'en_us';

package/src/commands/locale.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared locale type for feishu command i18n.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/core/accounts.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Lark multi-account management.
+ *
+ * Account overrides live under `cfg.channels.feishu.accounts`.
+ * Each account may override any top-level Feishu config field;
+ * unset fields fall back to the top-level defaults.
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+import type { ConfiguredLarkAccount, FeishuConfig, LarkAccount, LarkCredentials } from './types';
+/**
+ * List all account IDs defined in the Lark config.
+ *
+ * Returns `[DEFAULT_ACCOUNT_ID]` when no explicit accounts exist.
+ */
+export declare function getLarkAccountIds(cfg: ClawdbotConfig): string[];
+/** Return the first (default) account ID. */
+export declare function getDefaultLarkAccountId(cfg: ClawdbotConfig): string;
+/**
+ * Resolve a single account by merging the top-level config with
+ * account-level overrides.  Account fields take precedence.
+ *
+ * Falls back to the default account when `accountId` is omitted or `null`.
+ */
+export declare function getLarkAccount(cfg: ClawdbotConfig, accountId?: string | null): LarkAccount;
+/**
+ * Build an account-scoped config view for downstream helpers that read from
+ * `cfg.channels.feishu`.
+ *
+ * In multi-account mode, many runtime helpers expect the merged account config
+ * to already be exposed at `cfg.channels.feishu`. This mirrors the inbound
+ * path behavior so outbound/tooling code resolves per-account settings
+ * consistently.
+ *
+ * @param cfg - Original top-level plugin config
+ * @param accountId - Optional target account ID
+ * @returns Config with `channels.feishu` replaced by the merged account config
+ */
+export declare function createAccountScopedConfig(cfg: ClawdbotConfig, accountId?: string | null): ClawdbotConfig;
+/** Return all accounts that are both configured and enabled. */
+export declare function getEnabledLarkAccounts(cfg: ClawdbotConfig): LarkAccount[];
+/**
+ * Extract API credentials from a Feishu config fragment.
+ *
+ * Returns `null` when `appId` or `appSecret` is missing.
+ */
+export declare function getLarkCredentials(feishuCfg?: FeishuConfig): LarkCredentials | null;
+/** Type guard: narrow `LarkAccount` to `ConfiguredLarkAccount`. */
+export declare function isConfigured(account: LarkAccount): account is ConfiguredLarkAccount;

package/src/core/accounts.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Lark multi-account management.
+ *
+ * Account overrides live under `cfg.channels.feishu.accounts`.
+ * Each account may override any top-level Feishu config field;
+ * unset fields fall back to the top-level defaults.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLarkAccountIds = getLarkAccountIds;
+exports.getDefaultLarkAccountId = getDefaultLarkAccountId;
+exports.getLarkAccount = getLarkAccount;
+exports.createAccountScopedConfig = createAccountScopedConfig;
+exports.getEnabledLarkAccounts = getEnabledLarkAccounts;
+exports.getLarkCredentials = getLarkCredentials;
+exports.isConfigured = isConfigured;
+const account_id_1 = require("openclaw/plugin-sdk/account-id");
+const normalizeAccountId = typeof account_id_1.normalizeAccountId === 'function'
+    ? account_id_1.normalizeAccountId
+    : (id) => id?.trim().toLowerCase() || undefined;
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Extract the `channels.feishu` section from the top-level config. */
+function getLarkConfig(cfg) {
+    return cfg?.channels?.feishu;
+}
+/** Return the per-account override map, if present. */
+function getAccountMap(section) {
+    return section.accounts;
+}
+/** Strip the `accounts` key and return the remaining top-level config. */
+function baseConfig(section) {
+    const { accounts: _ignored, ...rest } = section;
+    return rest;
+}
+/** Merge base config with account override (account fields take precedence).
+ *  Performs a one-level deep merge for plain-object fields so that partial
+ *  account overrides (e.g. `footer: { model: false }`) are merged with
+ *  the base instead of replacing the entire object. */
+function mergeAccountConfig(base, override) {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        if (value === undefined)
+            continue;
+        const baseVal = base[key];
+        // Deep-merge plain objects one level (footer, tools, heartbeat, etc.)
+        if (value &&
+            typeof value === 'object' &&
+            !Array.isArray(value) &&
+            baseVal &&
+            typeof baseVal === 'object' &&
+            !Array.isArray(baseVal)) {
+            result[key] = { ...baseVal, ...value };
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/** Coerce a domain string to `LarkBrand`, defaulting to `"feishu"`. */
+function toBrand(domain) {
+    return domain ?? 'feishu';
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * List all account IDs defined in the Lark config.
+ *
+ * Returns `[DEFAULT_ACCOUNT_ID]` when no explicit accounts exist.
+ */
+function getLarkAccountIds(cfg) {
+    const section = getLarkConfig(cfg);
+    if (!section)
+        return [account_id_1.DEFAULT_ACCOUNT_ID];
+    const accountMap = getAccountMap(section);
+    if (!accountMap || Object.keys(accountMap).length === 0) {
+        return [account_id_1.DEFAULT_ACCOUNT_ID];
+    }
+    const accountIds = Object.keys(accountMap);
+    // 当 accounts 存在时，如果顶层也配置了 appId/appSecret（即默认机器人），
+    // 将 DEFAULT_ACCOUNT_ID 加入列表，确保顶层机器人不会被忽略。
+    // 但如果 accountMap 已经包含 default，则不重复添加。
+    const hasDefault = accountIds.some((id) => id.trim().toLowerCase() === account_id_1.DEFAULT_ACCOUNT_ID);
+    if (!hasDefault) {
+        const base = baseConfig(section);
+        if (base.appId && base.appSecret) {
+            return [account_id_1.DEFAULT_ACCOUNT_ID, ...accountIds];
+        }
+    }
+    return accountIds;
+}
+/** Return the first (default) account ID. */
+function getDefaultLarkAccountId(cfg) {
+    return getLarkAccountIds(cfg)[0];
+}
+/**
+ * Resolve a single account by merging the top-level config with
+ * account-level overrides.  Account fields take precedence.
+ *
+ * Falls back to the default account when `accountId` is omitted or `null`.
+ */
+function getLarkAccount(cfg, accountId) {
+    const requestedId = accountId ? (normalizeAccountId(accountId) ?? account_id_1.DEFAULT_ACCOUNT_ID) : account_id_1.DEFAULT_ACCOUNT_ID;
+    const section = getLarkConfig(cfg);
+    if (!section) {
+        return {
+            accountId: requestedId,
+            enabled: false,
+            configured: false,
+            brand: 'feishu',
+            config: {},
+        };
+    }
+    const base = baseConfig(section);
+    const accountMap = getAccountMap(section);
+    const accountOverride = accountMap && requestedId !== account_id_1.DEFAULT_ACCOUNT_ID
+        ? accountMap[requestedId]
+        : undefined;
+    const merged = accountOverride
+        ? mergeAccountConfig(base, accountOverride)
+        : { ...base };
+    const appId = merged.appId;
+    const appSecret = merged.appSecret;
+    const configured = !!(appId && appSecret);
+    // Respect explicit `enabled` when set; otherwise derive from `configured`.
+    const enabled = !!(merged.enabled ?? configured);
+    const brand = toBrand(merged.domain);
+    if (configured) {
+        return {
+            accountId: requestedId,
+            enabled,
+            configured: true,
+            name: merged.name ?? undefined,
+            appId: appId,
+            appSecret: appSecret,
+            encryptKey: merged.encryptKey ?? undefined,
+            verificationToken: merged.verificationToken ?? undefined,
+            brand,
+            config: merged,
+        };
+    }
+    return {
+        accountId: requestedId,
+        enabled,
+        configured: false,
+        name: merged.name ?? undefined,
+        appId: appId ?? undefined,
+        appSecret: appSecret ?? undefined,
+        encryptKey: merged.encryptKey ?? undefined,
+        verificationToken: merged.verificationToken ?? undefined,
+        brand,
+        config: merged,
+    };
+}
+/**
+ * Build an account-scoped config view for downstream helpers that read from
+ * `cfg.channels.feishu`.
+ *
+ * In multi-account mode, many runtime helpers expect the merged account config
+ * to already be exposed at `cfg.channels.feishu`. This mirrors the inbound
+ * path behavior so outbound/tooling code resolves per-account settings
+ * consistently.
+ *
+ * @param cfg - Original top-level plugin config
+ * @param accountId - Optional target account ID
+ * @returns Config with `channels.feishu` replaced by the merged account config
+ */
+function createAccountScopedConfig(cfg, accountId) {
+    const account = getLarkAccount(cfg, accountId);
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            feishu: account.config,
+        },
+    };
+}
+/** Return all accounts that are both configured and enabled. */
+function getEnabledLarkAccounts(cfg) {
+    const ids = getLarkAccountIds(cfg);
+    const results = [];
+    for (const id of ids) {
+        const account = getLarkAccount(cfg, id);
+        if (account.enabled && account.configured) {
+            results.push(account);
+        }
+    }
+    return results;
+}
+/**
+ * Extract API credentials from a Feishu config fragment.
+ *
+ * Returns `null` when `appId` or `appSecret` is missing.
+ */
+function getLarkCredentials(feishuCfg) {
+    if (!feishuCfg)
+        return null;
+    const appId = feishuCfg.appId;
+    const appSecret = feishuCfg.appSecret;
+    if (!appId || !appSecret)
+        return null;
+    return {
+        appId,
+        appSecret,
+        encryptKey: feishuCfg.encryptKey ?? undefined,
+        verificationToken: feishuCfg.verificationToken ?? undefined,
+        brand: toBrand(feishuCfg.domain),
+    };
+}
+/** Type guard: narrow `LarkAccount` to `ConfiguredLarkAccount`. */
+function isConfigured(account) {
+    return account.configured;
+}

package/src/core/agent-config.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Agent configuration helpers for the Lark/Feishu channel plugin.
+ *
+ * Reads agent-level configuration (identity, skills, tools, subagents)
+ * from the top-level `agents.list` in OpenClawConfig.  These helpers
+ * bridge the gap between the SDK's agent infrastructure and the Feishu
+ * plugin's dispatch/reply layers.
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+/** Minimal agent identity fields used by the Feishu plugin. */
+interface AgentIdentity {
+    name?: string;
+    emoji?: string;
+    avatar?: string;
+}
+/** Minimal agent tools policy fields. */
+interface AgentToolsPolicy {
+    allow?: string[];
+    deny?: string[];
+}
+/** Shape of an agent entry in `config.agents.list`. */
+interface AgentEntry {
+    id: string;
+    name?: string;
+    skills?: string[];
+    identity?: AgentIdentity;
+    tools?: AgentToolsPolicy & Record<string, unknown>;
+    subagents?: {
+        allowAgents?: string[];
+    };
+}
+/**
+ * Retrieve the full list of configured agents from config.
+ *
+ * @param cfg - The top-level application config.
+ * @returns Array of agent entries, or empty array if none configured.
+ */
+export declare function listConfiguredAgents(cfg: ClawdbotConfig): AgentEntry[];
+/**
+ * Look up a specific agent's configuration by its ID.
+ *
+ * @param cfg - The top-level application config.
+ * @param agentId - The agent ID to search for.
+ * @returns The matching agent entry, or `undefined` if not found.
+ */
+export declare function resolveAgentEntry(cfg: ClawdbotConfig, agentId: string): AgentEntry | undefined;
+/**
+ * Resolve a human-readable display name for an agent.
+ *
+ * Priority: `identity.name` > `name` > `undefined`.
+ *
+ * @param cfg - The top-level application config.
+ * @param agentId - The agent ID.
+ * @returns The display name, or `undefined` if none configured.
+ */
+export declare function getAgentDisplayName(cfg: ClawdbotConfig, agentId: string): string | undefined;
+/**
+ * Resolve the per-agent skills filter.
+ *
+ * @param cfg - The top-level application config.
+ * @param agentId - The agent ID.
+ * @returns Skill allowlist, or `undefined` if no agent-level filter.
+ */
+export declare function getAgentSkillsFilter(cfg: ClawdbotConfig, agentId: string): string[] | undefined;
+/**
+ * Resolve the per-agent tools policy (allow/deny lists).
+ *
+ * @param cfg - The top-level application config.
+ * @param agentId - The agent ID.
+ * @returns Tools policy object, or `undefined` if none configured.
+ */
+export declare function getAgentToolsPolicy(cfg: ClawdbotConfig, agentId: string): AgentToolsPolicy | undefined;
+/**
+ * Merge agent-level and group-level skill filters.
+ *
+ * When both are present, the effective filter is the intersection:
+ * a skill must appear in both lists to be included.  When only one
+ * is present, that list is used as-is.
+ *
+ * @param agentSkills - Per-agent skill allowlist (from AgentConfig.skills).
+ * @param groupSkills - Per-group skill allowlist (from FeishuGroupConfig.skills).
+ * @returns Merged skill filter, or `undefined` if neither is set.
+ */
+export declare function mergeSkillFilters(agentSkills: string[] | undefined, groupSkills: string[] | undefined): string[] | undefined;
+/**
+ * Check whether a tool name is permitted by an agent's tool policy.
+ *
+ * Evaluation order:
+ *   1. If `deny` list exists and tool matches → denied.
+ *   2. If `allow` list exists and tool does NOT match → denied.
+ *   3. Otherwise → allowed.
+ *
+ * Supports glob-like patterns with trailing `*` (e.g. `feishu_calendar_*`).
+ *
+ * @param toolName - The tool name being invoked.
+ * @param policy - The agent's tool policy.
+ * @returns `true` if the tool is allowed, `false` if denied.
+ */
+export declare function isToolAllowedByPolicy(toolName: string, policy: AgentToolsPolicy | undefined): boolean;
+export {};