lark-remote 0.1.0

package/dist/config/kimi-config.js

@@ -0,0 +1,111 @@
+/**
+ * Kimi config loader
+ *
+ * Dynamically reads available models from `kimi provider list --json`,
+ * provides dynamic dropdown options for /config card.
+ */
+import { execFileSync } from 'node:child_process';
+import { getLogger } from '../logger/index.js';
+/** Valid thinking effort values for kimi (Layer 1: Schema enum source) */
+export const KIMI_THINKING_EFFORTS = ['low', 'high', 'max'];
+/** Fallback efforts when all values are filtered out */
+export const FALLBACK_EFFORTS = ['low', 'high', 'max'];
+/** 清空缓存（测试与配置热更新用，与 codex/opencode 的 invalidate 对齐） */
+export function invalidateKimiConfigCache() {
+    kimiConfigCache = null;
+}
+/** Cache for loadKimiConfig to avoid repeated sync calls */
+let kimiConfigCache = null;
+const KIMI_CONFIG_CACHE_TTL_MS = 60000; // 1 minute TTL
+/**
+ * Load Kimi models from `kimi provider list --json`.
+ * Falls back to defaults if the command fails.
+ * Uses caching to avoid repeated sync calls.
+ */
+export function loadKimiConfig() {
+    const now = Date.now();
+    // Return cached result if still valid
+    if (kimiConfigCache && now - kimiConfigCache.timestamp < KIMI_CONFIG_CACHE_TTL_MS) {
+        return kimiConfigCache.result;
+    }
+    const logger = getLogger();
+    try {
+        const output = execFileSync('kimi', ['provider', 'list', '--json'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 10000,
+            maxBuffer: 2 * 1024 * 1024,
+        });
+        const data = JSON.parse(output.toString());
+        if (!data.models || Object.keys(data.models).length === 0) {
+            logger.warn('[kimi-config] no models found in provider list, using defaults');
+            return buildDefaultResult();
+        }
+        const modelOptions = [];
+        const modelDisplayNames = {};
+        const modelEfforts = {};
+        const modelDefaultEfforts = {};
+        for (const [modelId, modelInfo] of Object.entries(data.models)) {
+            modelOptions.push(modelId);
+            modelDisplayNames[modelId] = modelInfo.displayName;
+            // Layer 2: Filter effort values to only include valid ones from KIMI_THINKING_EFFORTS
+            const efforts = modelInfo.supportEfforts ?? [...FALLBACK_EFFORTS];
+            const filteredEfforts = efforts.filter((e) => KIMI_THINKING_EFFORTS.includes(e));
+            // Fallback to default if all filtered out
+            modelEfforts[modelId] = filteredEfforts.length > 0 ? filteredEfforts : [...FALLBACK_EFFORTS];
+            // Layer 2: Validate default effort, fallback to 'max' if invalid
+            const def = modelInfo.defaultEffort ?? 'max';
+            modelDefaultEfforts[modelId] = KIMI_THINKING_EFFORTS.includes(def)
+                ? def
+                : 'max';
+        }
+        // Find current default model from the first provider
+        let currentModel = 'kimi-code/k3';
+        if (data.models['kimi-code/k3']) {
+            currentModel = 'kimi-code/k3';
+        }
+        else if (modelOptions.length > 0) {
+            currentModel = modelOptions[0];
+        }
+        const result = {
+            currentModel,
+            modelOptions,
+            modelDisplayNames,
+            modelEfforts,
+            modelDefaultEfforts,
+        };
+        kimiConfigCache = { result, timestamp: Date.now() };
+        return result;
+    }
+    catch (err) {
+        logger.warn(`[kimi-config] failed to load models: ${err.message}, using defaults`);
+        const result = buildDefaultResult();
+        kimiConfigCache = { result, timestamp: Date.now() };
+        return result;
+    }
+}
+function buildDefaultResult() {
+    return {
+        currentModel: 'kimi-code/k3',
+        modelOptions: [
+            'kimi-code/k3',
+            'kimi-code/kimi-for-coding',
+            'kimi-code/kimi-for-coding-highspeed',
+        ],
+        modelDisplayNames: {
+            'kimi-code/k3': 'K3',
+            'kimi-code/kimi-for-coding': 'K2.7 Coding',
+            'kimi-code/kimi-for-coding-highspeed': 'K2.7 Coding Highspeed',
+        },
+        modelEfforts: {
+            'kimi-code/k3': ['low', 'high', 'max'],
+            'kimi-code/kimi-for-coding': ['low', 'high', 'max'],
+            'kimi-code/kimi-for-coding-highspeed': ['low', 'high', 'max'],
+        },
+        modelDefaultEfforts: {
+            'kimi-code/k3': 'max',
+            'kimi-code/kimi-for-coding': 'max',
+            'kimi-code/kimi-for-coding-highspeed': 'max',
+        },
+    };
+}
+//# sourceMappingURL=kimi-config.js.map

package/dist/config/opencode-config.d.ts

@@ -0,0 +1,20 @@
+/**
+ * OpenCode 配置读取工具
+ *
+ * 从 opencode models --verbose 命令获取 provider 和 model 信息
+ */
+interface OpencodeConfigResult {
+    /** provider 名称列表 */
+    providerNames: string[];
+    /** 根据 provider 获取可用模型列表（返回纯 model ID，不带 provider 前缀） */
+    modelOptions: (provider?: string) => string[];
+}
+/** 清空缓存（测试与配置热更新用，与 codex-config 的 invalidateCodexBundledCache 对齐） */
+export declare function invalidateOpencodeConfigCache(): void;
+/**
+ * 加载 opencode 配置，执行 opencode models --verbose 并解析
+ *
+ * @returns provider 列表和 model 查询接口
+ */
+export declare function loadOpencodeConfig(): OpencodeConfigResult;
+export {};

package/dist/config/opencode-config.js

@@ -0,0 +1,124 @@
+/**
+ * OpenCode 配置读取工具
+ *
+ * 从 opencode models --verbose 命令获取 provider 和 model 信息
+ */
+import { execSync } from 'node:child_process';
+import { getLogger } from '../logger/index.js';
+/**
+ * 内置的 fallback 列表
+ * 当 opencode 命令失败时使用
+ * 格式：provider/model（内部用，modelOptions 返回时会去掉 provider 前缀）
+ */
+const FALLBACK_PROVIDERS = [
+    'opencode',
+    'deepseek',
+    'minimax-cn-coding-plan',
+    'myprovider',
+    'volcengine-plan',
+];
+const FALLBACK_MODELS = {
+    opencode: ['big-pickle'],
+    deepseek: ['deepseek-chat'],
+    'minimax-cn-coding-plan': ['MiniMax-M2.5'],
+};
+/** 正缓存 TTL：opencode models 列表短时间不变，1 分钟（与 kimi-config 对齐） */
+const OPENCODE_CONFIG_CACHE_TTL_MS = 60_000;
+/**
+ * 失败负缓存 TTL：命令失败后 30s 内直接用 fallback，避免每次 /config 卡片构建
+ * 都同步阻塞事件循环最长 10s（§P1-8，与 codex-config 负缓存对齐）。
+ */
+const OPENCODE_NEGATIVE_CACHE_TTL_MS = 30_000;
+let opencodeConfigCache = null;
+let opencodeConfigFailedAt = null;
+/** 清空缓存（测试与配置热更新用，与 codex-config 的 invalidateCodexBundledCache 对齐） */
+export function invalidateOpencodeConfigCache() {
+    opencodeConfigCache = null;
+    opencodeConfigFailedAt = null;
+}
+function buildFallbackResult() {
+    return {
+        providerNames: FALLBACK_PROVIDERS,
+        modelOptions: (provider) => {
+            if (!provider) {
+                // 无 provider 时返回所有 model ID（去重）
+                const allModels = new Set();
+                for (const models of Object.values(FALLBACK_MODELS)) {
+                    for (const m of models) {
+                        allModels.add(m);
+                    }
+                }
+                return Array.from(allModels).sort();
+            }
+            return FALLBACK_MODELS[provider] ?? [];
+        },
+    };
+}
+/**
+ * 加载 opencode 配置，执行 opencode models --verbose 并解析
+ *
+ * @returns provider 列表和 model 查询接口
+ */
+export function loadOpencodeConfig() {
+    const now = Date.now();
+    // 正缓存命中：TTL 内不重复 execSync（P1-8）
+    if (opencodeConfigCache && now - opencodeConfigCache.timestamp < OPENCODE_CONFIG_CACHE_TTL_MS) {
+        return opencodeConfigCache.result;
+    }
+    // 失败负缓存：命令最近失败过，TTL 内直接用 fallback，不再同步阻塞
+    if (opencodeConfigFailedAt !== null &&
+        now - opencodeConfigFailedAt < OPENCODE_NEGATIVE_CACHE_TTL_MS) {
+        return buildFallbackResult();
+    }
+    try {
+        // 执行 opencode models --verbose 获取所有模型信息
+        const output = execSync('opencode models --verbose', {
+            encoding: 'utf-8',
+            // P1-8：30s → 10s，与 codex/kimi 对齐；maxBuffer 防模型清单 ENOBUFS 隐性截断
+            timeout: 10000,
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        // 按 provider 分组收集模型（只存 model ID，不存 provider/model 完整格式）
+        const providerModels = new Map();
+        // 解析输出：每个模型以 provider/model 格式开头，后面跟着 JSON 块
+        const lines = output.split('\n');
+        for (const line of lines) {
+            // 检测模型头如 "opencode/big-pickle" 或 "deepseek/deepseek-chat"
+            const match = line.match(/^([a-zA-Z0-9_-]+)\/([a-zA-Z0-9_.-]+)$/);
+            if (match) {
+                const providerID = match[1];
+                const modelID = match[2];
+                if (!providerModels.has(providerID)) {
+                    providerModels.set(providerID, []);
+                }
+                providerModels.get(providerID).push(modelID);
+            }
+        }
+        const providerNames = Array.from(providerModels.keys()).sort();
+        const modelOptions = (provider) => {
+            if (!provider) {
+                // 无 provider 时返回所有 model ID（去重）
+                const allModels = new Set();
+                for (const models of providerModels.values()) {
+                    for (const m of models) {
+                        allModels.add(m);
+                    }
+                }
+                return Array.from(allModels).sort();
+            }
+            return providerModels.get(provider) ?? [];
+        };
+        const result = { providerNames, modelOptions };
+        opencodeConfigCache = { result, timestamp: now };
+        opencodeConfigFailedAt = null;
+        return result;
+    }
+    catch (error) {
+        // 如果命令失败，使用 fallback
+        const logger = getLogger();
+        logger.warn(`[opencode-config] failed to load opencode models: ${error}`);
+        opencodeConfigFailedAt = now;
+        return buildFallbackResult();
+    }
+}
+//# sourceMappingURL=opencode-config.js.map

package/dist/config/pi-config.d.ts

@@ -0,0 +1,49 @@
+/**
+ * pi 配置读取工具
+ *
+ * 从 ~/.pi/agent/models.json 和 auth.json 读取 provider 和 model 信息
+ */
+interface PiProviderInfo {
+    /** Provider 名称 */
+    name: string;
+    /** API 端点（可选） */
+    baseUrl?: string;
+    /** API 类型 */
+    api?: string;
+    /** 该 provider 下的模型列表 */
+    models: string[];
+    /** 是否有认证信息 */
+    isAuthenticated: boolean;
+}
+/** loadPiConfig() 的返回类型，包含 provider 和 model 的聚合信息 */
+export interface PiConfigResult {
+    /** provider 名称列表 */
+    providerNames: string[];
+    /** 获取指定 provider 的 model 选项 */
+    modelOptions: (provider?: string) => string[];
+}
+/** @internal Exported for testing only — verify env var is respected. */
+export declare function _getModelsFilePath(): string;
+/** @internal Exported for testing only. */
+export declare function _getAuthFilePath(): string;
+/**
+ * 读取 pi 的 provider 和 model 配置
+ *
+ * @returns provider 列表，每个 provider 包含名称、模型列表和认证状态
+ */
+export declare function loadPiProviderConfig(): PiProviderInfo[];
+/**
+ * 聚合加载 pi 配置，只读一次文件，返回 provider 和 model 的查询接口
+ *
+ * 用于 buildConfigCard 等需要同时获取 provider 和 model 的场景，
+ * 避免重复 I/O。
+ */
+export declare function loadPiConfig(): PiConfigResult;
+/**
+ * 获取可用的 model 列表（纯 model ID，不带 provider 前缀）
+ *
+ * @param provider 可选，指定 provider 时只返回该 provider 的模型
+ * @returns model 名称数组（纯 modelId）
+ */
+export declare function getPiModelOptions(provider?: string): string[];
+export {};

package/dist/config/pi-config.js

@@ -0,0 +1,151 @@
+/**
+ * pi 配置读取工具
+ *
+ * 从 ~/.pi/agent/models.json 和 auth.json 读取 provider 和 model 信息
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * 解析 pi 配置目录。优先使用 PI_CONFIG_DIR 环境变量（测试隔离用），
+ * 默认 ~/.pi/agent。每次调用时动态读取环境变量，避免模块级缓存导致
+ * singleFork 模式下测试设置 env 过晚（与 CLAUDE_SETTINGS_PATH 模式类似，
+ * 但 pi-config 的常量原本在模块级求值，改为惰性求值以支持运行时切换）。
+ */
+function getPiConfigDir() {
+    return process.env.PI_CONFIG_DIR ?? path.join(os.homedir(), '.pi', 'agent');
+}
+/** @internal Exported for testing only — verify env var is respected. */
+export function _getModelsFilePath() {
+    return path.join(getPiConfigDir(), 'models.json');
+}
+/** @internal Exported for testing only. */
+export function _getAuthFilePath() {
+    return path.join(getPiConfigDir(), 'auth.json');
+}
+/**
+ * 内置的 fallback 列表（provider 和 model 同源）
+ * 当配置文件不存在时使用
+ *
+ * 语义约束：每个 provider fallback 都必须在此有至少 1 个 model，
+ * 每个 model 中出现的 provider 都必须在 provider fallback 中。
+ */
+const FALLBACK_ENTRIES = [
+    { modelId: 'glm-5.2', provider: 'Volcano' },
+    { modelId: 'glm-5.1', provider: 'lt' },
+    { modelId: 'claude-sonnet-4-20250514', provider: 'anthropic' },
+    { modelId: 'gpt-4o', provider: 'openai' },
+    { modelId: 'gemini-2.5-pro', provider: 'google' },
+    { modelId: 'deepseek-chat', provider: 'deepseek' },
+    { modelId: 'llama3', provider: 'ollama' },
+];
+function getPiProviderFallback() {
+    return [...new Set(FALLBACK_ENTRIES.map((e) => e.provider))];
+}
+function getPiModelFallback(provider) {
+    // 方案一：返回纯 model ID，不带 provider 后缀
+    const all = FALLBACK_ENTRIES.map((e) => e.modelId);
+    if (!provider)
+        return all;
+    return all.filter((m) => {
+        const entry = FALLBACK_ENTRIES.find((e) => e.modelId === m);
+        return entry?.provider === provider;
+    });
+}
+/**
+ * 读取 pi 的 provider 和 model 配置
+ *
+ * @returns provider 列表，每个 provider 包含名称、模型列表和认证状态
+ */
+export function loadPiProviderConfig() {
+    const results = new Map();
+    const modelsFile = _getModelsFilePath();
+    const authFile = _getAuthFilePath();
+    // 1. 读取 models.json
+    let modelsData = {};
+    if (fs.existsSync(modelsFile)) {
+        try {
+            modelsData = JSON.parse(fs.readFileSync(modelsFile, 'utf-8'));
+        }
+        catch {
+            // 文件格式错误，跳过
+        }
+    }
+    // 2. 读取 auth.json
+    let authData = {};
+    if (fs.existsSync(authFile)) {
+        try {
+            authData = JSON.parse(fs.readFileSync(authFile, 'utf-8')) ?? {};
+        }
+        catch {
+            // 文件格式错误，跳过
+        }
+    }
+    // 3. 从 models.json 提取 providers
+    const providers = modelsData.providers ?? {};
+    for (const [name, config] of Object.entries(providers)) {
+        const cfg = config;
+        results.set(name, {
+            name,
+            baseUrl: cfg.baseUrl,
+            api: cfg.api,
+            models: (cfg.models ?? []).map((m) => m.id),
+            isAuthenticated: !!authData[name],
+        });
+    }
+    // 4. 对于 auth.json 中有凭据但未在 models.json 中定义的 provider
+    //    添加为占位项
+    for (const name of Object.keys(authData)) {
+        if (!results.has(name)) {
+            results.set(name, {
+                name,
+                models: [],
+                isAuthenticated: true,
+            });
+        }
+    }
+    return Array.from(results.values());
+}
+/**
+ * 聚合加载 pi 配置，只读一次文件，返回 provider 和 model 的查询接口
+ *
+ * 用于 buildConfigCard 等需要同时获取 provider 和 model 的场景，
+ * 避免重复 I/O。
+ */
+export function loadPiConfig() {
+    const config = loadPiProviderConfig();
+    if (config.length === 0) {
+        return {
+            providerNames: getPiProviderFallback(),
+            modelOptions: (provider) => getPiModelFallback(provider),
+        };
+    }
+    const providerNames = config.map((p) => p.name);
+    const modelOptions = (provider) => {
+        const providers = provider ? config.filter((p) => p.name === provider) : config;
+        const models = [];
+        for (const p of providers) {
+            if (p.models.length > 0) {
+                for (const modelId of p.models) {
+                    // 方案一：返回纯 model ID，不带 provider 后缀
+                    models.push(modelId);
+                }
+            }
+        }
+        if (models.length === 0) {
+            return getPiModelFallback(provider);
+        }
+        return models;
+    };
+    return { providerNames, modelOptions };
+}
+/**
+ * 获取可用的 model 列表（纯 model ID，不带 provider 前缀）
+ *
+ * @param provider 可选，指定 provider 时只返回该 provider 的模型
+ * @returns model 名称数组（纯 modelId）
+ */
+export function getPiModelOptions(provider) {
+    return loadPiConfig().modelOptions(provider);
+}
+//# sourceMappingURL=pi-config.js.map

package/dist/config/wizard.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Ensure a usable config exists before `loadConfig` is called.
+ *
+ * - If credentials are already present, do nothing.
+ * - In an interactive terminal with missing credentials, run the QR-code
+ *   registration wizard and write the resulting credentials back to the
+ *   config file so startup can proceed.
+ * - In a non-interactive context, do nothing here; `loadConfig` will then
+ *   generate its template and exit with instructions (preserving the
+ *   original behavior for tests and headless setups).
+ */
+export declare function ensureConfig(configPath: string): Promise<void>;

package/dist/config/wizard.js

@@ -0,0 +1,84 @@
+import { registerApp } from '@larksuite/channel';
+import qrcode from 'qrcode-terminal';
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { AppConfigSchema } from './index.js';
+/**
+ * Run the QR-code registration wizard. The user scans the QR with their
+ * Feishu/Lark app to create a new application; the SDK polls until the
+ * creation completes and returns the credentials.
+ */
+async function runRegistrationWizard() {
+    console.log('\n[lark-remote] 未检测到飞书应用配置，进入扫码创建向导。\n');
+    const result = await registerApp({
+        source: 'lark-remote',
+        onQRCodeReady: (info) => {
+            console.log('请用飞书 App 扫描以下二维码完成应用创建：\n');
+            qrcode.generate(info.url, { small: true });
+            const mins = Math.max(1, Math.round(info.expireIn / 60));
+            console.log(`\n二维码有效期：约 ${mins} 分钟`);
+            console.log(`也可以直接在浏览器打开：${info.url}\n`);
+        },
+        onStatusChange: (info) => {
+            if (info.status === 'domain_switched') {
+                console.log('识别到国际版租户，已切换到 larksuite.com 域名。');
+            }
+            else if (info.status === 'slow_down') {
+                console.log('轮询速度过快，已自动降速。');
+            }
+        },
+    });
+    console.log('\n✓ 应用创建成功');
+    console.log(`  App ID:  ${result.client_id}`);
+    if (result.user_info?.tenant_brand) {
+        console.log(`  Tenant:  ${result.user_info.tenant_brand}`);
+    }
+    console.log('');
+    return { appId: result.client_id, appSecret: result.client_secret };
+}
+function isInteractiveTerminal() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/** True when the config file already has non-empty feishu credentials. */
+function hasFeishuCredentials(configPath) {
+    if (!fs.existsSync(configPath))
+        return false;
+    let parsed;
+    try {
+        parsed = YAML.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+    catch {
+        return false;
+    }
+    const feishu = parsed?.feishu;
+    return Boolean(feishu && feishu.appId && feishu.appSecret);
+}
+/** Persist a full config file seeded with the given feishu credentials. */
+function writeConfigWithCredentials(configPath, appId, appSecret) {
+    const dir = path.dirname(configPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const config = AppConfigSchema.parse({ feishu: { appId, appSecret } });
+    fs.writeFileSync(configPath, YAML.stringify(config), 'utf-8');
+}
+/**
+ * Ensure a usable config exists before `loadConfig` is called.
+ *
+ * - If credentials are already present, do nothing.
+ * - In an interactive terminal with missing credentials, run the QR-code
+ *   registration wizard and write the resulting credentials back to the
+ *   config file so startup can proceed.
+ * - In a non-interactive context, do nothing here; `loadConfig` will then
+ *   generate its template and exit with instructions (preserving the
+ *   original behavior for tests and headless setups).
+ */
+export async function ensureConfig(configPath) {
+    if (hasFeishuCredentials(configPath))
+        return;
+    if (!isInteractiveTerminal())
+        return;
+    const { appId, appSecret } = await runRegistrationWizard();
+    writeConfigWithCredentials(configPath, appId, appSecret);
+    console.log(`[lark-remote] 凭证已写入 ${configPath}，继续启动...\n`);
+}
+//# sourceMappingURL=wizard.js.map

package/dist/connector/file-limits.d.ts

@@ -0,0 +1,7 @@
+/**
+ * File upload size limit constant.
+ *
+ * Aligned with Feishu im/v1/files API limit (30MB for file_type=stream).
+ * Single source of truth — router and connector both import from here.
+ */
+export declare const MAX_FILE_UPLOAD_SIZE: number;

package/dist/connector/file-limits.js

@@ -0,0 +1,8 @@
+/**
+ * File upload size limit constant.
+ *
+ * Aligned with Feishu im/v1/files API limit (30MB for file_type=stream).
+ * Single source of truth — router and connector both import from here.
+ */
+export const MAX_FILE_UPLOAD_SIZE = 30 * 1024 * 1024; // 30MB
+//# sourceMappingURL=file-limits.js.map

package/dist/connector/index.d.ts

@@ -0,0 +1,86 @@
+import { type CardActionEvent, type CardActionResponse, type CardStreamProducer } from '@larksuite/channel';
+import type { AppConfig } from '../config/index.js';
+/**
+ * dedup 缓存 TTL（毫秒）。控制飞书事件去重窗口，全局作用于 message + cardAction。
+ *
+ * 必须远小于用户连击间隔，否则同一按钮的连续点击会被当成"重复事件"丢弃：
+ * - SDK 的 cardAction dedup eventId = `card:{messageId}:{operator.openId}:{actionId}`
+ * - actionId = `tag|name|option|JSON.stringify(value)`，不含时间戳/事件序号
+ * - config 卡片原地更新（updateCardInPlace），用户在同一张卡上连点 toggle：
+ *   messageId / operator / value 三段都相同 → eventId 完全相同 → 第二次点击被
+ *   seenCache drop，toggle 不可逆（"显示工具结果"等开关第二次点击静默失效）。
+ *
+ * SDK 默认 12h 太长；60s 仍会误伤连击。300ms 挡飞书瞬时重投递（<100ms 级），
+ * 放过用户连击（慢点两次通常 >500ms）。代价：削弱 message 秒级重投递防护——
+ * 飞书 WS 正常连接不重发，重连补发延迟常 >60s 本就挡不住，串行队列（§9.6）
+ * 还兜底防并发，影响可接受。
+ *
+ * 此 bug 无法在 stub connector 测试中复现（测试绕过 SDK safety 层）。
+ * 详见 design.md §9.8。原地更新逻辑新增按钮时参考该节去重风险分类。
+ */
+export declare const DEDUP_TTL_MS = 300;
+interface FeishuMessage {
+    userId: string;
+    messageId: string;
+    chatId: string;
+    content: string;
+}
+type MessageHandler = (msg: FeishuMessage) => void;
+/**
+ * CardAction handler may return a CardActionResponse (e.g. `{ toast: {...} }`)
+ * to give the clicking user native immediate feedback. The SDK passes the
+ * return value back to Feishu as the callback response. Returning void/undefined
+ * means "no immediate response" (original behavior).
+ */
+type CardActionHandler = (action: CardActionEvent) => void | CardActionResponse | Promise<void | CardActionResponse>;
+export declare class FeishuConnector {
+    private channel;
+    private onMessage?;
+    private onCardAction?;
+    private isConnected;
+    private appId;
+    private appSecret;
+    constructor(config: AppConfig);
+    get connected(): boolean;
+    setMessageHandler(handler: MessageHandler): void;
+    setCardActionHandler(handler: CardActionHandler): void;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    reconnect(): Promise<void>;
+    /**
+     * Send a message with automatic rate-limit retry (§9.5).
+     * Encounters rate_limited / feishuCode 99991400|99991401（SDK 归类为
+     * permission_denied）→ sleep 200ms → retry once.
+     */
+    sendWithRetry(chatId: string, input: {
+        text: string;
+    } | {
+        markdown: string;
+    } | {
+        card: object;
+    }, opts?: {
+        replyTo?: string;
+    }): Promise<string>;
+    streamCard(chatId: string, initial: object, producer: CardStreamProducer, opts?: {
+        replyTo?: string;
+    }): Promise<string>;
+    updateCard(messageId: string, card: object): Promise<void>;
+    /** Format error for logging without causing circular serialization */
+    private formatError;
+    addReaction(messageId: string, emoji: string): Promise<void>;
+    /**
+     * Upload a file to Feishu and send it to the specified chat.
+     * Uses the im/v1/files upload API.
+     */
+    sendFile(chatId: string, filePath: string): Promise<string>;
+    /**
+     * Cached tenant_access_token for sendFile (P2-18). The token is valid ~2h;
+     * fetching it on every file send wastes a round-trip and an unguarded fetch
+     * could return data.code != 0 with an undefined token. Cache with expiry and
+     * validate the response code.
+     */
+    private cachedToken;
+    private cachedTokenExpireAt;
+    private getTenantAccessToken;
+}
+export {};