@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/core/agent-config.js

@@ -0,0 +1,148 @@
+"use strict";
+// SPDX-License-Identifier: MIT
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listConfiguredAgents = listConfiguredAgents;
+exports.resolveAgentEntry = resolveAgentEntry;
+exports.getAgentDisplayName = getAgentDisplayName;
+exports.getAgentSkillsFilter = getAgentSkillsFilter;
+exports.getAgentToolsPolicy = getAgentToolsPolicy;
+exports.mergeSkillFilters = mergeSkillFilters;
+exports.isToolAllowedByPolicy = isToolAllowedByPolicy;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ */
+function listConfiguredAgents(cfg) {
+    const agents = cfg.agents;
+    return agents?.list ?? [];
+}
+/**
+ * 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.
+ */
+function resolveAgentEntry(cfg, agentId) {
+    return listConfiguredAgents(cfg).find((a) => a.id === agentId);
+}
+/**
+ * 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.
+ */
+function getAgentDisplayName(cfg, agentId) {
+    const entry = resolveAgentEntry(cfg, agentId);
+    if (!entry)
+        return undefined;
+    return entry.identity?.name ?? entry.name;
+}
+/**
+ * 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.
+ */
+function getAgentSkillsFilter(cfg, agentId) {
+    return resolveAgentEntry(cfg, agentId)?.skills;
+}
+/**
+ * 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.
+ */
+function getAgentToolsPolicy(cfg, agentId) {
+    const entry = resolveAgentEntry(cfg, agentId);
+    if (!entry?.tools)
+        return undefined;
+    const { allow, deny } = entry.tools;
+    if (!allow && !deny)
+        return undefined;
+    return { allow, deny };
+}
+/**
+ * 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.
+ */
+function mergeSkillFilters(agentSkills, groupSkills) {
+    if (!agentSkills && !groupSkills)
+        return undefined;
+    if (!agentSkills)
+        return groupSkills;
+    if (!groupSkills)
+        return agentSkills;
+    // Intersection: group filter narrows the agent filter.
+    const agentSet = new Set(agentSkills);
+    return groupSkills.filter((s) => agentSet.has(s));
+}
+/**
+ * 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.
+ */
+function isToolAllowedByPolicy(toolName, policy) {
+    if (!policy)
+        return true;
+    if (policy.deny && policy.deny.length > 0) {
+        if (matchesAnyPattern(toolName, policy.deny))
+            return false;
+    }
+    if (policy.allow && policy.allow.length > 0) {
+        return matchesAnyPattern(toolName, policy.allow);
+    }
+    return true;
+}
+/**
+ * Check whether a string matches any of the given patterns.
+ * Supports trailing `*` as a simple wildcard.
+ */
+function matchesAnyPattern(value, patterns) {
+    for (const pattern of patterns) {
+        if (pattern === '*')
+            return true;
+        if (pattern.endsWith('*')) {
+            if (value.startsWith(pattern.slice(0, -1)))
+                return true;
+        }
+        else if (value === pattern) {
+            return true;
+        }
+    }
+    return false;
+}

package/src/core/api-error.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared Lark API error handling utilities.
+ *
+ * Provides unified error handling for two distinct error paths:
+ *
+ * 1. **Response-level errors** — The SDK returns a response object with a
+ *    non-zero `code`.  Handled by {@link assertLarkOk}.
+ *
+ * 2. **Thrown exceptions** — The SDK throws an Axios-style error (HTTP 4xx)
+ *    whose properties include the Feishu error `code` and `msg`.
+ *    Handled by {@link formatLarkError}.
+ *
+ * Both paths intercept well-known codes (e.g. LARK_ERROR.APP_SCOPE_MISSING (99991672) — missing API scopes)
+ * and produce user-friendly messages with actionable authorization links.
+ */
+/**
+ * 从 Lark SDK 抛错对象中提取飞书 API code。
+ *
+ * 支持三种常见结构：
+ * - `{ code }` — SDK 直接挂载
+ * - `{ data: { code } }` — 响应体嵌套
+ * - `{ response: { data: { code } } }` — Axios 风格
+ */
+export declare function extractLarkApiCode(err: unknown): number | undefined;
+/**
+ * Assert that a Lark SDK response is successful (code === 0).
+ *
+ * For permission errors (code LARK_ERROR.APP_SCOPE_MISSING (99991672)), the thrown error includes the
+ * required scope names and a direct authorization URL so the AI can
+ * present it to the end user.
+ */
+export declare function assertLarkOk(res: {
+    code?: number;
+    msg?: string;
+}): void;
+/**
+ * Extract a meaningful error message from a thrown Lark SDK / Axios error.
+ *
+ * The Lark SDK throws Axios errors whose object carries Feishu-specific
+ * fields (`code`, `msg`) alongside the standard `message`.  For permission
+ * errors (LARK_ERROR.APP_SCOPE_MISSING (99991672)) we format a user-friendly string with scopes + auth URL.
+ * For all other errors we try `err.msg` first (the Feishu detail) and fall
+ * back to `err.message` (the generic Axios text).
+ */
+export declare function formatLarkError(err: unknown): string;

package/src/core/api-error.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared Lark API error handling utilities.
+ *
+ * Provides unified error handling for two distinct error paths:
+ *
+ * 1. **Response-level errors** — The SDK returns a response object with a
+ *    non-zero `code`.  Handled by {@link assertLarkOk}.
+ *
+ * 2. **Thrown exceptions** — The SDK throws an Axios-style error (HTTP 4xx)
+ *    whose properties include the Feishu error `code` and `msg`.
+ *    Handled by {@link formatLarkError}.
+ *
+ * Both paths intercept well-known codes (e.g. LARK_ERROR.APP_SCOPE_MISSING (99991672) — missing API scopes)
+ * and produce user-friendly messages with actionable authorization links.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractLarkApiCode = extractLarkApiCode;
+exports.assertLarkOk = assertLarkOk;
+exports.formatLarkError = formatLarkError;
+const permission_url_1 = require("./permission-url.js");
+const auth_errors_1 = require("./auth-errors.js");
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Given a Feishu error code and msg, format a user-friendly permission
+ * error string if the code is LARK_ERROR.APP_SCOPE_MISSING (99991672).  Returns `null` for other codes.
+ */
+function formatPermissionError(code, msg) {
+    if (code !== auth_errors_1.LARK_ERROR.APP_SCOPE_MISSING)
+        return null;
+    const authUrl = (0, permission_url_1.extractPermissionGrantUrl)(msg);
+    const scopes = (0, permission_url_1.extractPermissionScopes)(msg);
+    return `权限不足：应用缺少 [${scopes}] 权限。\n` + `请管理员点击以下链接申请并开通权限：\n${authUrl}`;
+}
+// ---------------------------------------------------------------------------
+// Code extraction
+// ---------------------------------------------------------------------------
+function coerceCode(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+/**
+ * 从 Lark SDK 抛错对象中提取飞书 API code。
+ *
+ * 支持三种常见结构：
+ * - `{ code }` — SDK 直接挂载
+ * - `{ data: { code } }` — 响应体嵌套
+ * - `{ response: { data: { code } } }` — Axios 风格
+ */
+function extractLarkApiCode(err) {
+    if (!err || typeof err !== 'object')
+        return undefined;
+    const e = err;
+    return coerceCode(e.code) ?? coerceCode(e.data?.code) ?? coerceCode(e.response?.data?.code);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Assert that a Lark SDK response is successful (code === 0).
+ *
+ * For permission errors (code LARK_ERROR.APP_SCOPE_MISSING (99991672)), the thrown error includes the
+ * required scope names and a direct authorization URL so the AI can
+ * present it to the end user.
+ */
+function assertLarkOk(res) {
+    if (!res.code || res.code === 0)
+        return;
+    const permMsg = formatPermissionError(res.code, res.msg ?? '');
+    if (permMsg)
+        throw new Error(permMsg);
+    throw new Error(res.msg ?? `Feishu API error (code: ${res.code})`);
+}
+/**
+ * Extract a meaningful error message from a thrown Lark SDK / Axios error.
+ *
+ * The Lark SDK throws Axios errors whose object carries Feishu-specific
+ * fields (`code`, `msg`) alongside the standard `message`.  For permission
+ * errors (LARK_ERROR.APP_SCOPE_MISSING (99991672)) we format a user-friendly string with scopes + auth URL.
+ * For all other errors we try `err.msg` first (the Feishu detail) and fall
+ * back to `err.message` (the generic Axios text).
+ */
+function formatLarkError(err) {
+    if (!err || typeof err !== 'object') {
+        return String(err);
+    }
+    const e = err;
+    // Path 1: Lark SDK merges Feishu fields onto the thrown error object.
+    if (typeof e.code === 'number' && e.msg) {
+        const permMsg = formatPermissionError(e.code, e.msg);
+        if (permMsg)
+            return permMsg;
+        return e.msg;
+    }
+    // Path 2: Standard Axios error — dig into response.data.
+    const data = e.response?.data;
+    if (data && typeof data.code === 'number' && data.msg) {
+        const permMsg = formatPermissionError(data.code, data.msg);
+        if (permMsg)
+            return permMsg;
+        return data.msg;
+    }
+    // Fallback.
+    return e.message ?? String(err);
+}

package/src/core/app-owner-fallback.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * 应用所有者查询 — 复用 app-scope-checker 的 API 调用和统一 owner 定义。
+ *
+ * 所有 owner 判定统一使用 {@link getAppInfo} 返回的 `effectiveOwnerOpenId`。
+ * 不维护独立缓存，完全依赖 app-scope-checker 的 30s 缓存。
+ */
+import type * as Lark from '@larksuiteoapi/node-sdk';
+import type { ConfiguredLarkAccount } from './types';
+/**
+ * 获取应用的 effectiveOwnerOpenId。
+ *
+ * 复用 app-scope-checker 的 API 调用、缓存和统一 owner 定义（effectiveOwnerOpenId）。
+ * 查询失败时返回 undefined（fail-open）。
+ *
+ * @param account - 已配置的飞书账号信息
+ * @param sdk - 飞书 SDK 实例（必须已初始化 TAT）
+ * @returns 应用所有者的 open_id，如果查询失败则返回 undefined
+ */
+export declare function getAppOwnerFallback(account: ConfiguredLarkAccount, sdk: Lark.Client): Promise<string | undefined>;

package/src/core/app-owner-fallback.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * 应用所有者查询 — 复用 app-scope-checker 的 API 调用和统一 owner 定义。
+ *
+ * 所有 owner 判定统一使用 {@link getAppInfo} 返回的 `effectiveOwnerOpenId`。
+ * 不维护独立缓存，完全依赖 app-scope-checker 的 30s 缓存。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAppOwnerFallback = getAppOwnerFallback;
+const app_scope_checker_1 = require("./app-scope-checker.js");
+const lark_logger_1 = require("./lark-logger.js");
+const log = (0, lark_logger_1.larkLogger)('core/app-owner-fallback');
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * 获取应用的 effectiveOwnerOpenId。
+ *
+ * 复用 app-scope-checker 的 API 调用、缓存和统一 owner 定义（effectiveOwnerOpenId）。
+ * 查询失败时返回 undefined（fail-open）。
+ *
+ * @param account - 已配置的飞书账号信息
+ * @param sdk - 飞书 SDK 实例（必须已初始化 TAT）
+ * @returns 应用所有者的 open_id，如果查询失败则返回 undefined
+ */
+async function getAppOwnerFallback(account, sdk) {
+    const { appId } = account;
+    try {
+        const appInfo = await (0, app_scope_checker_1.getAppInfo)(sdk, appId);
+        return appInfo.effectiveOwnerOpenId;
+    }
+    catch (err) {
+        log.warn(`failed to get owner for ${appId}: ${err instanceof Error ? err.message : err}`);
+        return undefined; // fail-open: 获取失败不阻塞业务
+    }
+}

package/src/core/app-scope-checker.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * App Scope Checker — 查询应用已开通的 scope 列表。
+ *
+ * 通过 `GET /open-apis/application/v6/applications/:app_id` (TAT) 获取
+ * 应用信息，从 `app.scopes` 中提取已开通的 scope 字符串列表。
+ *
+ * 结果带 30 秒内存缓存，避免每次 invoke() 都调远程 API。
+ * scope 检查失败后可调 {@link invalidateAppScopeCache} 清缓存重查。
+ */
+import type * as Lark from '@larksuiteoapi/node-sdk';
+export interface AppInfo {
+    appId: string;
+    creatorId?: string;
+    ownerOpenId?: string;
+    ownerType?: number;
+    /**
+     * 统一的 owner 判定结果。所有需要判定"谁是应用 owner"的场景都应使用此字段。
+     *
+     * 规则：owner_type=2（企业内成员）时取 owner_id，否则回退 creator_id。
+     * 兼容 owner.owner_type 和 owner.type 两种字段名。
+     */
+    effectiveOwnerOpenId?: string;
+    scopes: Array<{
+        scope: string;
+        token_types?: string[];
+    }>;
+}
+/** 清除指定 appId 的缓存。 */
+export declare function invalidateAppScopeCache(appId: string): void;
+/**
+ * 获取应用已开通的 scope 列表。
+ *
+ * 需要应用自身有 `application:application:self_manage` 权限。
+ * `appId` 可传 `"me"` 查自己。
+ *
+ * @param sdk - Lark SDK 实例
+ * @param appId - 应用 ID
+ * @param tokenType - token 类型，用于过滤只支持特定 token 类型的 scope
+ * @returns scope 字符串数组，如 `["calendar:calendar", "task:task:write"]`
+ */
+export declare function getAppGrantedScopes(sdk: Lark.Client, appId: string, tokenType?: 'user' | 'tenant'): Promise<string[]>;
+/**
+ * 获取应用信息，包括 owner 信息。
+ *
+ * 复用 getAppGrantedScopes 的 API 调用和缓存。
+ * 如果缓存中已有数据且未过期，直接从缓存提取。
+ *
+ * @param sdk - Lark SDK 实例
+ * @param appId - 应用 ID（可传 "me"）
+ */
+export declare function getAppInfo(sdk: Lark.Client, appId: string): Promise<AppInfo>;
+/**
+ * 计算 APP 已有 ∩ OAPI 需要 的交集。
+ *
+ * 用于传给 OAuth 的 scope 参数 — 只请求 APP 已开通且 API 需要的 scope。
+ *
+ * @param appGranted - 应用已开通的 scope 列表
+ * @param apiRequired - OAPI 要求的 scope 列表
+ * @returns 交集 scope 列表
+ */
+export declare function intersectScopes(appGranted: string[], apiRequired: string[]): string[];
+/**
+ * 计算 OAPI 需要但 APP 未开通的 scope（差集）。
+ *
+ * 用于 AppScopeMissingError 的 missingScopes。
+ *
+ * @param appGranted - 应用已开通的 scope 列表
+ * @param apiRequired - OAPI 要求的 scope 列表
+ * @returns 缺失的 scope 列表
+ */
+export declare function missingScopes(appGranted: string[], apiRequired: string[]): string[];
+/**
+ * 校验应用已开通的 scope 是否满足要求。
+ *
+ * 与 tool-client.ts invoke() 的 scope 校验逻辑完全一致，作为唯一真值来源：
+ *   - `scopeNeedType === "all"`: appScopes 必须包含 requiredScopes 的全部项
+ *   - 其他（默认 "one"）:        appScopes 与 requiredScopes 的交集非空即可
+ *   - appScopes 为空:            视为满足（API 查询失败，退回服务端判断）
+ *
+ * @param appScopes      - 应用已开通的 scope 列表（由 getAppGrantedScopes 返回）
+ * @param requiredScopes - 需要的 scope 列表
+ * @param scopeNeedType  - "all" 表示全部必须，undefined/"one" 表示任一即可
+ */
+export declare function isAppScopeSatisfied(appScopes: string[], requiredScopes: string[], scopeNeedType?: 'one' | 'all'): boolean;

package/src/core/app-scope-checker.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * App Scope Checker — 查询应用已开通的 scope 列表。
+ *
+ * 通过 `GET /open-apis/application/v6/applications/:app_id` (TAT) 获取
+ * 应用信息，从 `app.scopes` 中提取已开通的 scope 字符串列表。
+ *
+ * 结果带 30 秒内存缓存，避免每次 invoke() 都调远程 API。
+ * scope 检查失败后可调 {@link invalidateAppScopeCache} 清缓存重查。
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.invalidateAppScopeCache = invalidateAppScopeCache;
+exports.getAppGrantedScopes = getAppGrantedScopes;
+exports.getAppInfo = getAppInfo;
+exports.intersectScopes = intersectScopes;
+exports.missingScopes = missingScopes;
+exports.isAppScopeSatisfied = isAppScopeSatisfied;
+const lark_logger_1 = require("./lark-logger.js");
+const log = (0, lark_logger_1.larkLogger)('core/app-scope-checker');
+const auth_errors_1 = require("./auth-errors.js");
+// ---------------------------------------------------------------------------
+// Cache
+// ---------------------------------------------------------------------------
+const cache = new Map();
+const CACHE_TTL_MS = 30 * 1000; // 30 秒
+/** 清除指定 appId 的缓存。 */
+function invalidateAppScopeCache(appId) {
+    cache.delete(appId);
+}
+// ---------------------------------------------------------------------------
+// Fetch
+// ---------------------------------------------------------------------------
+/**
+ * 获取应用已开通的 scope 列表。
+ *
+ * 需要应用自身有 `application:application:self_manage` 权限。
+ * `appId` 可传 `"me"` 查自己。
+ *
+ * @param sdk - Lark SDK 实例
+ * @param appId - 应用 ID
+ * @param tokenType - token 类型，用于过滤只支持特定 token 类型的 scope
+ * @returns scope 字符串数组，如 `["calendar:calendar", "task:task:write"]`
+ */
+async function getAppGrantedScopes(sdk, appId, tokenType) {
+    // 1. 检查缓存
+    const cached = cache.get(appId);
+    if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+        // 从缓存中过滤出支持当前 token 类型的 scope
+        return cached.rawScopes
+            .filter((s) => {
+            if (tokenType && s.token_types && Array.isArray(s.token_types)) {
+                return s.token_types.includes(tokenType);
+            }
+            return true;
+        })
+            .map((s) => s.scope);
+    }
+    // 2. 调用 API
+    try {
+        const res = await sdk.request({
+            method: 'GET',
+            url: `/open-apis/application/v6/applications/${appId}`,
+            params: { lang: 'zh_cn' },
+        });
+        if (res.code !== 0) {
+            // 任何 API 错误都认为是应用缺少 application:application:self_manage 权限
+            throw new auth_errors_1.AppScopeCheckFailedError(appId);
+        }
+        // 响应结构: res.data.app.scopes → [{ scope: "xxx", description, level, token_types?: string[] }]
+        // 或者从 app_version 中获取 scopes
+        const app = res.data?.app ?? res.app ?? res.data;
+        const rawScopes = app?.scopes ?? app?.online_version?.scopes ?? [];
+        // 提取并验证 scope 字符串
+        const validScopes = rawScopes
+            .filter((s) => typeof s.scope === 'string' && s.scope.length > 0)
+            .map((s) => ({ scope: s.scope, token_types: s.token_types }));
+        // 3. 写缓存（缓存完整数据，包含 token_types 和原始 app 对象）
+        cache.set(appId, { rawScopes: validScopes, rawApp: app, fetchedAt: Date.now() });
+        log.info(`fetched ${validScopes.length} scopes for app ${appId}`);
+        // 4. 根据 tokenType 过滤
+        const scopes = validScopes
+            .filter((s) => {
+            if (tokenType && s.token_types && Array.isArray(s.token_types)) {
+                return s.token_types.includes(tokenType);
+            }
+            return true;
+        })
+            .map((s) => s.scope);
+        log.info(`returning ${scopes.length} scopes${tokenType ? ` for ${tokenType} token` : ''}`);
+        return scopes;
+    }
+    catch (err) {
+        // 如果是 AppScopeCheckFailedError，重新抛出（不吞掉）
+        if (err instanceof auth_errors_1.AppScopeCheckFailedError) {
+            throw err;
+        }
+        // 检查是否是权限相关的 HTTP 错误（400/403）
+        // axios/SDK 异常对象通常包含 response.status 或 status 字段
+        const statusCode = err?.response?.status || err?.status || err?.statusCode;
+        const isPermissionError = statusCode === 400 ||
+            statusCode === 403 ||
+            (err instanceof Error && (err.message.includes('status code 400') || err.message.includes('status code 403')));
+        if (isPermissionError) {
+            throw new auth_errors_1.AppScopeCheckFailedError(appId);
+        }
+        log.warn(`failed to fetch scopes for ${appId}: ${err instanceof Error ? err.message : err}`);
+        // 其他查询失败不阻塞调用，返回空数组（后续 API 调用如果缺 scope 会被服务端拒绝）
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
+// App info
+// ---------------------------------------------------------------------------
+/**
+ * 获取应用信息，包括 owner 信息。
+ *
+ * 复用 getAppGrantedScopes 的 API 调用和缓存。
+ * 如果缓存中已有数据且未过期，直接从缓存提取。
+ *
+ * @param sdk - Lark SDK 实例
+ * @param appId - 应用 ID（可传 "me"）
+ */
+async function getAppInfo(sdk, appId) {
+    // 先确保缓存已填充（调一次 getAppGrantedScopes 来触发 API + 缓存）
+    await getAppGrantedScopes(sdk, appId);
+    const cached = cache.get(appId);
+    const rawApp = cached?.rawApp;
+    // 提取 owner 信息
+    const owner = rawApp?.owner;
+    const creatorId = rawApp?.creator_id;
+    // 统一 owner 定义：type=2（企业内成员）用 owner_id，否则回退 creator_id
+    // 兼容两种字段名（owner_type 和 type）
+    const ownerTypeValue = owner?.owner_type ?? owner?.type;
+    const effectiveOwnerOpenId = ownerTypeValue === 2 && owner?.owner_id ? owner.owner_id : (creatorId ?? owner?.owner_id);
+    return {
+        appId,
+        creatorId,
+        ownerOpenId: owner?.owner_id,
+        ownerType: owner?.owner_type,
+        effectiveOwnerOpenId,
+        scopes: cached?.rawScopes ?? [],
+    };
+}
+// ---------------------------------------------------------------------------
+// Scope intersection
+// ---------------------------------------------------------------------------
+/**
+ * 计算 APP 已有 ∩ OAPI 需要 的交集。
+ *
+ * 用于传给 OAuth 的 scope 参数 — 只请求 APP 已开通且 API 需要的 scope。
+ *
+ * @param appGranted - 应用已开通的 scope 列表
+ * @param apiRequired - OAPI 要求的 scope 列表
+ * @returns 交集 scope 列表
+ */
+function intersectScopes(appGranted, apiRequired) {
+    const grantedSet = new Set(appGranted);
+    return apiRequired.filter((s) => grantedSet.has(s));
+}
+/**
+ * 计算 OAPI 需要但 APP 未开通的 scope（差集）。
+ *
+ * 用于 AppScopeMissingError 的 missingScopes。
+ *
+ * @param appGranted - 应用已开通的 scope 列表
+ * @param apiRequired - OAPI 要求的 scope 列表
+ * @returns 缺失的 scope 列表
+ */
+function missingScopes(appGranted, apiRequired) {
+    const grantedSet = new Set(appGranted);
+    return apiRequired.filter((s) => !grantedSet.has(s));
+}
+/**
+ * 校验应用已开通的 scope 是否满足要求。
+ *
+ * 与 tool-client.ts invoke() 的 scope 校验逻辑完全一致，作为唯一真值来源：
+ *   - `scopeNeedType === "all"`: appScopes 必须包含 requiredScopes 的全部项
+ *   - 其他（默认 "one"）:        appScopes 与 requiredScopes 的交集非空即可
+ *   - appScopes 为空:            视为满足（API 查询失败，退回服务端判断）
+ *
+ * @param appScopes      - 应用已开通的 scope 列表（由 getAppGrantedScopes 返回）
+ * @param requiredScopes - 需要的 scope 列表
+ * @param scopeNeedType  - "all" 表示全部必须，undefined/"one" 表示任一即可
+ */
+function isAppScopeSatisfied(appScopes, requiredScopes, scopeNeedType) {
+    if (appScopes.length === 0)
+        return true; // API 查询失败 → 退回服务端判断
+    if (requiredScopes.length === 0)
+        return true;
+    if (scopeNeedType === 'all') {
+        return missingScopes(appScopes, requiredScopes).length === 0;
+    }
+    return intersectScopes(appScopes, requiredScopes).length > 0;
+}