@larksuite/openclaw-lark 2026.3.9

package/src/core/token-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-store.js","sourceRoot":"","sources":["../../../src/core/token-store.ts"],"names":[],"mappings":"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"}

package/src/core/tool-client.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * ToolClient — 工具层统一客户端。
+ *
+ * 专为 `src/tools/` 下的工具设计，封装 account 解析、SDK 管理、
+ * TAT/UAT 自动切换和 scope 预检。工具代码只需声明 API 名称和调用逻辑，
+ * 身份选择/scope 校验/token 管理全部由 `invoke()` 内聚处理。
+ *
+ * 用法：
+ * ```typescript
+ * const client = createToolClient(config);
+ *
+ * // UAT 调用 — 通过 { as: "user" } 指定用户身份
+ * const res = await client.invoke(
+ *   "calendar.v4.calendarEvent.create",
+ *   (sdk, opts) => sdk.calendar.calendarEvent.create(payload, opts),
+ *   { as: "user" },
+ * );
+ *
+ * // TAT 调用 — 默认走应用身份
+ * const res = await client.invoke(
+ *   "calendar.v4.calendar.list",
+ *   (sdk) => sdk.calendar.calendar.list(payload),
+ *   { as: "tenant" },
+ * );
+ * ```
+ */
+import * as Lark from '@larksuiteoapi/node-sdk';
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+import type { ConfiguredLarkAccount } from './types';
+import { type ToolActionKey } from './scope-manager';
+import { LARK_ERROR, NeedAuthorizationError, AppScopeCheckFailedError, AppScopeMissingError, UserAuthRequiredError, UserScopeInsufficientError } from './auth-errors';
+import type { ScopeErrorInfo, AuthHint, TryInvokeResult } from './auth-errors';
+export { LARK_ERROR, NeedAuthorizationError, AppScopeCheckFailedError, AppScopeMissingError, UserAuthRequiredError, UserScopeInsufficientError, };
+export type { ScopeErrorInfo, AuthHint, TryInvokeResult };
+/** Per-request options returned by `Lark.withUserAccessToken()`. */
+type LarkRequestOptions = ReturnType<typeof Lark.withUserAccessToken>;
+/**
+ * @deprecated 使用 `InvokeFn` 代替。
+ * Callback that receives the SDK client and per-request UAT options.
+ */
+export type ApiFn<T> = (sdk: Lark.Client, opts: LarkRequestOptions) => Promise<T>;
+/**
+ * invoke() 的回调签名。
+ *
+ * - UAT 模式：`opts` 为 `Lark.withUserAccessToken(token)`，需传给 SDK 方法；`uat` 为 User Access Token 原始字符串
+ * - TAT 模式：`opts` 为 `undefined`，SDK 默认走应用身份；`uat` 也为 `undefined`
+ */
+export type InvokeFn<T> = (sdk: Lark.Client, opts?: LarkRequestOptions, uat?: string) => Promise<T>;
+/** invoke() 的选项。 */
+export interface InvokeOptions {
+    /** 强制 token 类型。省略时根据 API meta 自动选择（优先 user）。 */
+    as?: 'user' | 'tenant';
+    /** 覆盖 senderOpenId。 */
+    userOpenId?: string;
+}
+/** invokeByPath() 的选项 — 在 InvokeOptions 基础上增加 HTTP 请求参数。 */
+export type InvokeByPathOptions = InvokeOptions & {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    query?: Record<string, string>;
+    /** 自定义请求 header，会与 Authorization / Content-Type 合并（自定义优先）。 */
+    headers?: Record<string, string>;
+};
+export declare class ToolClient {
+    readonly config: ClawdbotConfig;
+    /** 当前解析的账号信息（appId、appSecret 保证存在）。 */
+    readonly account: ConfiguredLarkAccount;
+    /** 当前请求的用户 open_id（来自 LarkTicket，可能为 undefined）。 */
+    readonly senderOpenId: string | undefined;
+    /** Lark SDK 实例（TAT 身份），直接调用即可。 */
+    readonly sdk: Lark.Client;
+    constructor(params: {
+        account: ConfiguredLarkAccount;
+        senderOpenId: string | undefined;
+        sdk: Lark.Client;
+        config: ClawdbotConfig;
+    });
+    /**
+     * 统一 API 调用入口。
+     *
+     * 自动处理：
+     * - 根据 API meta 选择 UAT / TAT
+     * - 严格模式：检查应用和用户是否拥有所有 API 要求的 scope
+     * - 无 token 或 scope 不足时抛出结构化错误
+     * - UAT 模式下复用 callWithUAT 的 refresh + retry
+     *
+     * @param apiName - meta.json 中的 toolName，如 `"calendar.v4.calendarEvent.create"`
+     * @param fn - API 调用逻辑。UAT 时 opts 已注入 token，TAT 时 opts 为 undefined。
+     * @param options - 可选配置：
+     *   - `as`: 指定 UAT/TAT
+     *   - `userOpenId`: 覆盖用户 ID
+     *
+     * @throws {@link AppScopeMissingError} 应用未开通 API 所需 scope
+     * @throws {@link UserAuthRequiredError} 用户未授权或 scope 不足
+     * @throws {@link UserScopeInsufficientError} 服务端报用户 scope 不足
+     *
+     * @example
+     * // UAT 调用 — 通过 { as: "user" } 指定
+     * const res = await client.invoke(
+     *   "calendar.v4.calendarEvent.create",
+     *   (sdk, opts) => sdk.calendar.calendarEvent.create(payload, opts),
+     *   { as: "user" },
+     * );
+     *
+     * @example
+     * // TAT 调用
+     * const res = await client.invoke(
+     *   "calendar.v4.calendar.list",
+     *   (sdk) => sdk.calendar.calendar.list(payload),
+     *   { as: "tenant" },
+     * );
+     *
+     */
+    invoke<T>(toolAction: ToolActionKey, fn: InvokeFn<T>, options?: InvokeOptions): Promise<T>;
+    /**
+     * 内部 invoke 实现，只支持 ToolActionKey（严格类型检查）
+     */
+    private _invokeInternal;
+    /**
+     * invoke() 的非抛出包装，适用于"允许失败"的子操作。
+     *
+     * - 成功 → `{ ok: true, data }`
+     * - 用户授权错误（可通过 OAuth 恢复）→ `{ ok: false, authHint }`
+     * - 应用权限缺失 / appScopeVerified=false → **仍然 throw**（需管理员操作）
+     * - 其他错误 → `{ ok: false, error }`
+     */
+    /**
+     * 对 SDK 未覆盖的飞书 API 发起 raw HTTP 请求，同时复用 invoke() 的
+     * auth/scope/refresh 全链路。
+     *
+     * @param apiName - 逻辑 API 名称（用于日志和错误信息），如 `"im.v1.chatP2p.batchQuery"`
+     * @param path - API 路径（以 `/open-apis/` 开头），如 `"/open-apis/im/v1/chat_p2p/batch_query"`
+     * @param options - HTTP 方法、body、query 及 InvokeOptions（as、userOpenId 等）
+     *
+     * @example
+     * ```typescript
+     * const res = await client.invokeByPath<{ data: { items: Array<{ chat_id: string }> } }>(
+     *   "im.v1.chatP2p.batchQuery",
+     *   "/open-apis/im/v1/chat_p2p/batch_query",
+     *   {
+     *     method: "POST",
+     *     body: { chatter_ids: [openId] },
+     *     as: "user",
+     *   },
+     * );
+     * ```
+     */
+    invokeByPath<T = any>(toolAction: ToolActionKey, path: string, options?: InvokeByPathOptions): Promise<T>;
+    private invokeAsTenant;
+    private invokeAsUser;
+    /**
+     * 发起 raw HTTP 请求到飞书 API，委托 rawLarkRequest 处理。
+     */
+    private rawRequest;
+    /**
+     * 识别飞书服务端错误码并转换为结构化错误。
+     *
+     * - LARK_ERROR.APP_SCOPE_MISSING (99991672) → AppScopeMissingError（清缓存后抛出）
+     * - LARK_ERROR.USER_SCOPE_INSUFFICIENT (99991679) → UserScopeInsufficientError
+     */
+    private rethrowStructuredError;
+}
+/**
+ * 从配置创建 {@link ToolClient}。
+ *
+ * 自动从当前 {@link LarkTicket} 解析 accountId 和 senderOpenId。
+ * 如果 LarkTicket 不可用（如非消息场景），回退到 `accountIndex`
+ * 指定的账号。
+ *
+ * @param config - OpenClaw 配置对象
+ * @param accountIndex - 回退账号索引（默认 0）
+ */
+export declare function createToolClient(config: ClawdbotConfig, accountIndex?: number): ToolClient;
+//# sourceMappingURL=tool-client.d.ts.map

package/src/core/tool-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-client.d.ts","sourceRoot":"","sources":["../../../src/core/tool-client.ts"],"names":[],"mappings":"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"}

package/src/core/tool-client.js

@@ -0,0 +1,381 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * ToolClient — 工具层统一客户端。
+ *
+ * 专为 `src/tools/` 下的工具设计，封装 account 解析、SDK 管理、
+ * TAT/UAT 自动切换和 scope 预检。工具代码只需声明 API 名称和调用逻辑，
+ * 身份选择/scope 校验/token 管理全部由 `invoke()` 内聚处理。
+ *
+ * 用法：
+ * ```typescript
+ * const client = createToolClient(config);
+ *
+ * // UAT 调用 — 通过 { as: "user" } 指定用户身份
+ * const res = await client.invoke(
+ *   "calendar.v4.calendarEvent.create",
+ *   (sdk, opts) => sdk.calendar.calendarEvent.create(payload, opts),
+ *   { as: "user" },
+ * );
+ *
+ * // TAT 调用 — 默认走应用身份
+ * const res = await client.invoke(
+ *   "calendar.v4.calendar.list",
+ *   (sdk) => sdk.calendar.calendar.list(payload),
+ *   { as: "tenant" },
+ * );
+ * ```
+ */
+import * as Lark from '@larksuiteoapi/node-sdk';
+import { getLarkAccount, getEnabledLarkAccounts } from './accounts';
+import { LarkClient } from './lark-client';
+import { getTicket } from './lark-ticket';
+import { callWithUAT } from './uat-client';
+import { getStoredToken } from './token-store';
+import { getAppGrantedScopes, invalidateAppScopeCache, missingScopes } from './app-scope-checker';
+import { getAppOwnerFallback } from './app-owner-fallback';
+import { larkLogger } from './lark-logger';
+import { getRequiredScopes } from './scope-manager';
+import { rawLarkRequest } from './raw-request';
+import { assertOwnerAccessStrict } from './owner-policy';
+import { LARK_ERROR, NeedAuthorizationError, AppScopeCheckFailedError, AppScopeMissingError, UserAuthRequiredError, UserScopeInsufficientError, } from './auth-errors';
+// Re-export for backward compatibility — 下游模块可继续从 tool-client 导入
+export { LARK_ERROR, NeedAuthorizationError, AppScopeCheckFailedError, AppScopeMissingError, UserAuthRequiredError, UserScopeInsufficientError, };
+const tcLog = larkLogger('core/tool-client');
+// ---------------------------------------------------------------------------
+// ToolClient
+// ---------------------------------------------------------------------------
+export class ToolClient {
+    config;
+    /** 当前解析的账号信息（appId、appSecret 保证存在）。 */
+    account;
+    /** 当前请求的用户 open_id（来自 LarkTicket，可能为 undefined）。 */
+    senderOpenId;
+    /** Lark SDK 实例（TAT 身份），直接调用即可。 */
+    sdk;
+    constructor(params) {
+        this.account = params.account;
+        this.senderOpenId = params.senderOpenId;
+        this.sdk = params.sdk;
+        this.config = params.config;
+    }
+    // -------------------------------------------------------------------------
+    // invoke() — 统一 API 调用入口
+    // -------------------------------------------------------------------------
+    /**
+     * 统一 API 调用入口。
+     *
+     * 自动处理：
+     * - 根据 API meta 选择 UAT / TAT
+     * - 严格模式：检查应用和用户是否拥有所有 API 要求的 scope
+     * - 无 token 或 scope 不足时抛出结构化错误
+     * - UAT 模式下复用 callWithUAT 的 refresh + retry
+     *
+     * @param apiName - meta.json 中的 toolName，如 `"calendar.v4.calendarEvent.create"`
+     * @param fn - API 调用逻辑。UAT 时 opts 已注入 token，TAT 时 opts 为 undefined。
+     * @param options - 可选配置：
+     *   - `as`: 指定 UAT/TAT
+     *   - `userOpenId`: 覆盖用户 ID
+     *
+     * @throws {@link AppScopeMissingError} 应用未开通 API 所需 scope
+     * @throws {@link UserAuthRequiredError} 用户未授权或 scope 不足
+     * @throws {@link UserScopeInsufficientError} 服务端报用户 scope 不足
+     *
+     * @example
+     * // UAT 调用 — 通过 { as: "user" } 指定
+     * const res = await client.invoke(
+     *   "calendar.v4.calendarEvent.create",
+     *   (sdk, opts) => sdk.calendar.calendarEvent.create(payload, opts),
+     *   { as: "user" },
+     * );
+     *
+     * @example
+     * // TAT 调用
+     * const res = await client.invoke(
+     *   "calendar.v4.calendar.list",
+     *   (sdk) => sdk.calendar.calendar.list(payload),
+     *   { as: "tenant" },
+     * );
+     *
+     */
+    async invoke(toolAction, fn, options) {
+        return this._invokeInternal(toolAction, fn, options);
+    }
+    /**
+     * 内部 invoke 实现，只支持 ToolActionKey（严格类型检查）
+     */
+    async _invokeInternal(toolAction, fn, options) {
+        // 检查旧版插件是否已禁用 (error)
+        const feishuEntry = this.config.plugins?.entries?.feishu;
+        if (feishuEntry && feishuEntry.enabled !== false) {
+            throw new Error('❌ 检测到旧版插件未禁用。\n' +
+                '👉 请依次运行命令：\n' +
+                '```\n' +
+                'openclaw config set plugins.entries.feishu.enabled false --json\n' +
+                'openclaw gateway restart\n' +
+                '```');
+        }
+        // 2. 从 scope.ts 查询 API 需要的 scopes（Required Scopes）
+        const requiredScopes = getRequiredScopes(toolAction);
+        // 3. 决定 token 类型（默认 user，用户可通过 options.as 覆盖）
+        const tokenType = options?.as ?? 'user';
+        // ---- App Granted Scopes 检查（应用已开通的权限）----
+        // UAT 调用额外检查 offline_access（OAuth Device Flow 的前提权限），
+        // 但不加入 requiredScopes（避免阻断业务 scope 进入用户授权流程）。
+        const appCheckScopes = tokenType === 'user' ? [...new Set([...requiredScopes, 'offline_access'])] : requiredScopes;
+        let appScopeVerified = true;
+        if (appCheckScopes.length > 0) {
+            const appGrantedScopes = await getAppGrantedScopes(this.sdk, this.account.appId, tokenType);
+            if (appGrantedScopes.length > 0) {
+                // 严格模式：应用必须开通所有 Required Scopes（+ offline_access）
+                const missingAppScopes = missingScopes(appGrantedScopes, appCheckScopes);
+                if (missingAppScopes.length > 0) {
+                    throw new AppScopeMissingError({ apiName: toolAction, scopes: missingAppScopes, appId: this.account.appId }, 'all', tokenType, requiredScopes);
+                }
+            }
+            else {
+                // 查询失败（返回空数组）→ 标记 appScopeVerified=false，跳过本地 scope 预检，
+                // 让服务端来判断是应用缺权限还是用户缺授权。
+                appScopeVerified = false;
+            }
+        }
+        // 5. 执行调用
+        if (tokenType === 'tenant') {
+            return this.invokeAsTenant(toolAction, fn, requiredScopes);
+        }
+        // 5.1 获取 userOpenId，支持兜底逻辑
+        let userOpenId = options?.userOpenId ?? this.senderOpenId;
+        // 5.2 兜底逻辑：如果没有 senderOpenId，尝试使用应用所有者
+        if (!userOpenId) {
+            const fallbackUserId = await getAppOwnerFallback(this.account, this.sdk);
+            if (fallbackUserId) {
+                userOpenId = fallbackUserId;
+                tcLog.info(`Using app owner as fallback user`, {
+                    toolAction,
+                    appId: this.account.appId,
+                    ownerId: fallbackUserId,
+                });
+            }
+        }
+        return this.invokeAsUser(toolAction, fn, requiredScopes, userOpenId, appScopeVerified);
+    }
+    /**
+     * invoke() 的非抛出包装，适用于"允许失败"的子操作。
+     *
+     * - 成功 → `{ ok: true, data }`
+     * - 用户授权错误（可通过 OAuth 恢复）→ `{ ok: false, authHint }`
+     * - 应用权限缺失 / appScopeVerified=false → **仍然 throw**（需管理员操作）
+     * - 其他错误 → `{ ok: false, error }`
+     */
+    // -------------------------------------------------------------------------
+    // invokeByPath() — SDK 未覆盖的 API 调用入口
+    // -------------------------------------------------------------------------
+    /**
+     * 对 SDK 未覆盖的飞书 API 发起 raw HTTP 请求，同时复用 invoke() 的
+     * auth/scope/refresh 全链路。
+     *
+     * @param apiName - 逻辑 API 名称（用于日志和错误信息），如 `"im.v1.chatP2p.batchQuery"`
+     * @param path - API 路径（以 `/open-apis/` 开头），如 `"/open-apis/im/v1/chat_p2p/batch_query"`
+     * @param options - HTTP 方法、body、query 及 InvokeOptions（as、userOpenId 等）
+     *
+     * @example
+     * ```typescript
+     * const res = await client.invokeByPath<{ data: { items: Array<{ chat_id: string }> } }>(
+     *   "im.v1.chatP2p.batchQuery",
+     *   "/open-apis/im/v1/chat_p2p/batch_query",
+     *   {
+     *     method: "POST",
+     *     body: { chatter_ids: [openId] },
+     *     as: "user",
+     *   },
+     * );
+     * ```
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async invokeByPath(toolAction, path, options) {
+        const fn = async (_sdk, _opts, uat) => {
+            return this.rawRequest(path, {
+                method: options?.method,
+                body: options?.body,
+                query: options?.query,
+                headers: options?.headers,
+                accessToken: uat,
+            });
+        };
+        return this._invokeInternal(toolAction, fn, options);
+    }
+    // -------------------------------------------------------------------------
+    // Private: TAT path
+    // -------------------------------------------------------------------------
+    async invokeAsTenant(toolAction, fn, requiredScopes) {
+        try {
+            return await fn(this.sdk);
+        }
+        catch (err) {
+            this.rethrowStructuredError(err, toolAction, requiredScopes, undefined, 'tenant');
+            throw err;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Private: UAT path
+    // -------------------------------------------------------------------------
+    async invokeAsUser(toolAction, fn, requiredScopes, userOpenId, appScopeVerified) {
+        if (!userOpenId) {
+            throw new UserAuthRequiredError('unknown', {
+                apiName: toolAction,
+                scopes: requiredScopes,
+                appScopeVerified,
+                appId: this.account.appId,
+            });
+        }
+        // Owner 检查：非 owner 用户直接拒绝（从 uat-client.ts 迁移至此）
+        await assertOwnerAccessStrict(this.account, this.sdk, userOpenId);
+        // 预检：是否有已存储的 token
+        const stored = await getStoredToken(this.account.appId, userOpenId);
+        if (!stored) {
+            throw new UserAuthRequiredError(userOpenId, {
+                apiName: toolAction,
+                scopes: requiredScopes,
+                appScopeVerified,
+                appId: this.account.appId,
+            });
+        }
+        // 预检：token 的 scope 是否满足 API 要求
+        // ---- User Granted Scopes 检查（用户授权的权限）----
+        // 仅在 App Granted Scopes 检查成功时进行本地预检。
+        // 当 App Scope 检查失败时（appScopeVerified=false），跳过预检，
+        // 让请求走到服务端 — 服务端会返回准确的错误码：
+        //   LARK_ERROR.APP_SCOPE_MISSING (99991672) → App Granted Scopes 缺失（管理员需在开放平台开通）
+        //   LARK_ERROR.USER_SCOPE_INSUFFICIENT (99991679) → User Granted Scopes 缺失（需引导用户 OAuth 授权）
+        if (appScopeVerified && stored.scope && requiredScopes.length > 0) {
+            // 检查用户是否授权了所有 Required Scopes
+            const userGrantedScopes = new Set(stored.scope.split(/\s+/).filter(Boolean));
+            const missingUserScopes = requiredScopes.filter((s) => !userGrantedScopes.has(s));
+            if (missingUserScopes.length > 0) {
+                throw new UserAuthRequiredError(userOpenId, {
+                    apiName: toolAction,
+                    scopes: missingUserScopes,
+                    appScopeVerified,
+                    appId: this.account.appId,
+                });
+            }
+        }
+        // 通过 callWithUAT 执行（自动 refresh + retry）
+        try {
+            return await callWithUAT({
+                userOpenId,
+                appId: this.account.appId,
+                appSecret: this.account.appSecret,
+                domain: this.account.brand,
+            }, (accessToken) => fn(this.sdk, Lark.withUserAccessToken(accessToken), accessToken));
+        }
+        catch (err) {
+            if (err instanceof NeedAuthorizationError) {
+                throw new UserAuthRequiredError(userOpenId, {
+                    apiName: toolAction,
+                    scopes: requiredScopes,
+                    appScopeVerified,
+                });
+            }
+            this.rethrowStructuredError(err, toolAction, requiredScopes, userOpenId, 'user');
+            throw err;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Private: raw HTTP request
+    // -------------------------------------------------------------------------
+    /**
+     * 发起 raw HTTP 请求到飞书 API，委托 rawLarkRequest 处理。
+     */
+    async rawRequest(path, options) {
+        return rawLarkRequest({
+            brand: this.account.brand,
+            path,
+            ...options,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Private: structured error detection
+    // -------------------------------------------------------------------------
+    /**
+     * 识别飞书服务端错误码并转换为结构化错误。
+     *
+     * - LARK_ERROR.APP_SCOPE_MISSING (99991672) → AppScopeMissingError（清缓存后抛出）
+     * - LARK_ERROR.USER_SCOPE_INSUFFICIENT (99991679) → UserScopeInsufficientError
+     */
+    rethrowStructuredError(err, apiName, effectiveScopes, userOpenId, tokenType) {
+        const code = 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        err?.code ?? err?.response?.data?.code;
+        if (code === LARK_ERROR.APP_SCOPE_MISSING) {
+            // 应用 scope 不足 — 清缓存（管理员可能刚开通）
+            invalidateAppScopeCache(this.account.appId);
+            throw new AppScopeMissingError({
+                apiName,
+                scopes: effectiveScopes,
+                appId: this.account.appId,
+            }, 'all', tokenType);
+        }
+        if (code === LARK_ERROR.USER_SCOPE_INSUFFICIENT && userOpenId) {
+            throw new UserScopeInsufficientError(userOpenId, {
+                apiName,
+                scopes: effectiveScopes,
+            });
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * 从配置创建 {@link ToolClient}。
+ *
+ * 自动从当前 {@link LarkTicket} 解析 accountId 和 senderOpenId。
+ * 如果 LarkTicket 不可用（如非消息场景），回退到 `accountIndex`
+ * 指定的账号。
+ *
+ * @param config - OpenClaw 配置对象
+ * @param accountIndex - 回退账号索引（默认 0）
+ */
+export function createToolClient(config, accountIndex = 0) {
+    const ticket = getTicket();
+    // 1. 解析账号
+    let account;
+    if (ticket?.accountId) {
+        const resolved = getLarkAccount(config, ticket.accountId);
+        if (!resolved.configured) {
+            throw new Error(`Feishu account "${ticket.accountId}" is not configured (missing appId or appSecret). ` +
+                `Please check channels.feishu.accounts.${ticket.accountId} in your config.`);
+        }
+        if (!resolved.enabled) {
+            throw new Error(`Feishu account "${ticket.accountId}" is disabled. ` +
+                `Set channels.feishu.accounts.${ticket.accountId}.enabled to true, or remove it to use defaults.`);
+        }
+        account = resolved;
+    }
+    if (!account) {
+        const accounts = getEnabledLarkAccounts(config);
+        if (accounts.length === 0) {
+            throw new Error('No enabled Feishu accounts configured. ' + 'Please add appId and appSecret in config under channels.feishu');
+        }
+        if (accountIndex >= accounts.length) {
+            throw new Error(`Requested account index ${accountIndex} but only ${accounts.length} accounts available`);
+        }
+        const fallback = accounts[accountIndex];
+        if (!fallback.configured) {
+            throw new Error(`Account at index ${accountIndex} is not fully configured (missing appId or appSecret)`);
+        }
+        account = fallback;
+    }
+    // 2. 获取 SDK 实例（复用 LarkClient 的缓存）
+    const larkClient = LarkClient.fromAccount(account);
+    // 3. 组装 ToolClient
+    return new ToolClient({
+        account,
+        senderOpenId: ticket?.senderOpenId,
+        sdk: larkClient.sdk,
+        config,
+    });
+}
+//# sourceMappingURL=tool-client.js.map

package/src/core/tool-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-client.js","sourceRoot":"","sources":["../../../src/core/tool-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,IAAI,MAAM,yBAAyB,CAAC;AAGhD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAClG,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAsB,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EACL,UAAU,EACV,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,eAAe,CAAC;AAGvB,iEAAiE;AACjE,OAAO,EACL,UAAU,EACV,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,GAC3B,CAAC;AAGF,MAAM,KAAK,GAAG,UAAU,CAAC,kBAAkB,CAAC,CAAC;AA0C7C,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,MAAM,OAAO,UAAU;IACZ,MAAM,CAAiB;IAChC,uCAAuC;IAC9B,OAAO,CAAwB;IAExC,oDAAoD;IAC3C,YAAY,CAAqB;IAE1C,kCAAkC;IACzB,GAAG,CAAc;IAE1B,YAAY,MAKX;QACC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;QACxC,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,4EAA4E;IAC5E,yBAAyB;IACzB,4EAA4E;IAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,KAAK,CAAC,MAAM,CAAI,UAAyB,EAAE,EAAe,EAAE,OAAuB;QACjF,OAAO,IAAI,CAAC,eAAe,CAAC,UAAU,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IACvD,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,eAAe,CAAI,UAAyB,EAAE,EAAe,EAAE,OAAuB;QAClG,sBAAsB;QACtB,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC;QACzD,IAAI,WAAW,IAAI,WAAW,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;YACjD,MAAM,IAAI,KAAK,CACb,iBAAiB;gBACf,eAAe;gBACf,OAAO;gBACP,mEAAmE;gBACnE,4BAA4B;gBAC5B,KAAK,CACR,CAAC;QACJ,CAAC;QAED,mDAAmD;QACnD,MAAM,cAAc,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;QAErD,8CAA8C;QAC9C,MAAM,SAAS,GAAG,OAAO,EAAE,EAAE,IAAI,MAAM,CAAC;QAExC,2CAA2C;QAC3C,sDAAsD;QACtD,8CAA8C;QAC9C,MAAM,cAAc,GAAG,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,cAAc,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC;QAEnH,IAAI,gBAAgB,GAAG,IAAI,CAAC;QAC5B,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,MAAM,gBAAgB,GAAG,MAAM,mBAAmB,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAE5F,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChC,kDAAkD;gBAClD,MAAM,gBAAgB,GAAG,aAAa,CAAC,gBAAgB,EAAE,cAAc,CAAC,CAAC;gBACzE,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAChC,MAAM,IAAI,oBAAoB,CAC5B,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAC5E,KAAK,EACL,SAAS,EACT,cAAc,CACf,CAAC;gBACJ,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,wDAAwD;gBACxD,wBAAwB;gBACxB,gBAAgB,GAAG,KAAK,CAAC;YAC3B,CAAC;QACH,CAAC;QAED,UAAU;QACV,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;YAC3B,OAAO,IAAI,CAAC,cAAc,CAAC,UAAU,EAAE,EAAE,EAAE,cAAc,CAAC,CAAC;QAC7D,CAAC;QAED,2BAA2B;QAC3B,IAAI,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,IAAI,CAAC,YAAY,CAAC;QAE1D,uCAAuC;QACvC,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,cAAc,GAAG,MAAM,mBAAmB,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;YACzE,IAAI,cAAc,EAAE,CAAC;gBACnB,UAAU,GAAG,cAAc,CAAC;gBAC5B,KAAK,CAAC,IAAI,CAAC,kCAAkC,EAAE;oBAC7C,UAAU;oBACV,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;oBACzB,OAAO,EAAE,cAAc;iBACxB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,EAAE,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC;IACzF,CAAC;IAED;;;;;;;OAOG;IACH,4EAA4E;IAC5E,qCAAqC;IACrC,4EAA4E;IAE5E;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,8DAA8D;IAC9D,KAAK,CAAC,YAAY,CAAU,UAAyB,EAAE,IAAY,EAAE,OAA6B;QAChG,MAAM,EAAE,GAAgB,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACjD,OAAO,IAAI,CAAC,UAAU,CAAI,IAAI,EAAE;gBAC9B,MAAM,EAAE,OAAO,EAAE,MAAM;gBACvB,IAAI,EAAE,OAAO,EAAE,IAAI;gBACnB,KAAK,EAAE,OAAO,EAAE,KAAK;gBACrB,OAAO,EAAE,OAAO,EAAE,OAAO;gBACzB,WAAW,EAAE,GAAG;aACjB,CAAC,CAAC;QACL,CAAC,CAAC;QACF,OAAO,IAAI,CAAC,eAAe,CAAC,UAAU,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IACvD,CAAC;IAED,4EAA4E;IAC5E,oBAAoB;IACpB,4EAA4E;IAEpE,KAAK,CAAC,cAAc,CAAI,UAAyB,EAAE,EAAe,EAAE,cAAwB;QAClG,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,sBAAsB,CAAC,GAAG,EAAE,UAAU,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;YAClF,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,oBAAoB;IACpB,4EAA4E;IAEpE,KAAK,CAAC,YAAY,CACxB,UAAyB,EACzB,EAAe,EACf,cAAwB,EACxB,UAA8B,EAC9B,gBAAyB;QAEzB,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,qBAAqB,CAAC,SAAS,EAAE;gBACzC,OAAO,EAAE,UAAU;gBACnB,MAAM,EAAE,cAAc;gBACtB,gBAAgB;gBAChB,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;aAC1B,CAAC,CAAC;QACL,CAAC;QAED,gDAAgD;QAChD,MAAM,uBAAuB,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QAElE,mBAAmB;QACnB,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;QACpE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,qBAAqB,CAAC,UAAU,EAAE;gBAC1C,OAAO,EAAE,UAAU;gBACnB,MAAM,EAAE,cAAc;gBACtB,gBAAgB;gBAChB,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;aAC1B,CAAC,CAAC;QACL,CAAC;QAED,+BAA+B;QAC/B,2CAA2C;QAC3C,qCAAqC;QACrC,kDAAkD;QAClD,2BAA2B;QAC3B,iFAAiF;QACjF,2FAA2F;QAC3F,IAAI,gBAAgB,IAAI,MAAM,CAAC,KAAK,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClE,8BAA8B;YAC9B,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;YAC7E,MAAM,iBAAiB,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAClF,IAAI,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACjC,MAAM,IAAI,qBAAqB,CAAC,UAAU,EAAE;oBAC1C,OAAO,EAAE,UAAU;oBACnB,MAAM,EAAE,iBAAiB;oBACzB,gBAAgB;oBAChB,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;iBAC1B,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,wCAAwC;QACxC,IAAI,CAAC;YACH,OAAO,MAAM,WAAW,CACtB;gBACE,UAAU;gBACV,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;gBACzB,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS;gBACjC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;aAC3B,EACD,CAAC,WAAW,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,mBAAmB,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,CAClF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,sBAAsB,EAAE,CAAC;gBAC1C,MAAM,IAAI,qBAAqB,CAAC,UAAU,EAAE;oBAC1C,OAAO,EAAE,UAAU;oBACnB,MAAM,EAAE,cAAc;oBACtB,gBAAgB;iBACjB,CAAC,CAAC;YACL,CAAC;YACD,IAAI,CAAC,sBAAsB,CAAC,GAAG,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;YACjF,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,4BAA4B;IAC5B,4EAA4E;IAE5E;;OAEG;IACK,KAAK,CAAC,UAAU,CACtB,IAAY,EACZ,OAMC;QAED,OAAO,cAAc,CAAI;YACvB,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;YACzB,IAAI;YACJ,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,sCAAsC;IACtC,4EAA4E;IAE5E;;;;;OAKG;IACK,sBAAsB,CAC5B,GAAY,EACZ,OAAe,EACf,eAAyB,EACzB,UAAmB,EACnB,SAA6B;QAE7B,MAAM,IAAI;QACR,8DAA8D;QAC7D,GAAW,EAAE,IAAI,IAAK,GAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC;QAE3D,IAAI,IAAI,KAAK,UAAU,CAAC,iBAAiB,EAAE,CAAC;YAC1C,8BAA8B;YAC9B,uBAAuB,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC5C,MAAM,IAAI,oBAAoB,CAC5B;gBACE,OAAO;gBACP,MAAM,EAAE,eAAe;gBACvB,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;aAC1B,EACD,KAAK,EACL,SAAS,CACV,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,KAAK,UAAU,CAAC,uBAAuB,IAAI,UAAU,EAAE,CAAC;YAC9D,MAAM,IAAI,0BAA0B,CAAC,UAAU,EAAE;gBAC/C,OAAO;gBACP,MAAM,EAAE,eAAe;aACxB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;CACF;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAsB,EAAE,YAAY,GAAG,CAAC;IACvE,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAE3B,UAAU;IACV,IAAI,OAA0C,CAAC;IAE/C,IAAI,MAAM,EAAE,SAAS,EAAE,CAAC;QACtB,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QAC1D,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,mBAAmB,MAAM,CAAC,SAAS,oDAAoD;gBACrF,yCAAyC,MAAM,CAAC,SAAS,kBAAkB,CAC9E,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,mBAAmB,MAAM,CAAC,SAAS,iBAAiB;gBAClD,gCAAgC,MAAM,CAAC,SAAS,iDAAiD,CACpG,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,QAAQ,CAAC;IACrB,CAAC;IAED,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,QAAQ,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;QAChD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,yCAAyC,GAAG,gEAAgE,CAC7G,CAAC;QACJ,CAAC;QACD,IAAI,YAAY,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,2BAA2B,YAAY,aAAa,QAAQ,CAAC,MAAM,qBAAqB,CAAC,CAAC;QAC5G,CAAC;QACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;QACxC,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,oBAAoB,YAAY,uDAAuD,CAAC,CAAC;QAC3G,CAAC;QACD,OAAO,GAAG,QAAQ,CAAC;IACrB,CAAC;IAED,kCAAkC;IAClC,MAAM,UAAU,GAAG,UAAU,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAEnD,mBAAmB;IACnB,OAAO,IAAI,UAAU,CAAC;QACpB,OAAO;QACP,YAAY,EAAE,MAAM,EAAE,YAAY;QAClC,GAAG,EAAE,UAAU,CAAC,GAAG;QACnB,MAAM;KACP,CAAC,CAAC;AACL,CAAC"}