lark-kiro-bridge 0.3.1

package/dist/index.d.ts

@@ -0,0 +1,592 @@
+import * as lark from '@larksuiteoapi/node-sdk';
+import { Logger } from 'pino';
+import { z } from 'zod';
+
+/**
+ * 业务层使用的精简飞书事件类型。
+ * 把飞书 SDK 的复杂结构压平成 bridge 关心的字段。
+ */
+type ChatType = 'p2p' | 'group' | 'topic_group' | 'unknown';
+interface IncomingMessage {
+    /** 事件 id，用于去重和日志关联 */
+    eventId: string;
+    /** 飞书 message id */
+    messageId: string;
+    /** 飞书 chat id（DM 或群） */
+    chatId: string;
+    /** 主题群里的 thread id，普通群/DM 为 undefined */
+    threadId?: string;
+    /** 单聊 / 群聊 / 主题群 */
+    chatType: ChatType;
+    /** 发送者的 open_id（飞书租户内稳定 id） */
+    senderOpenId: string;
+    /** 消息类型：text、post、image、file、... */
+    messageType: string;
+    /** 原始 content（JSON 字符串，由飞书发来），具体结构因 messageType 而异 */
+    rawContent: string;
+    /** 已抽取的纯文本（仅 text/post 类型；其他类型为空字符串） */
+    text: string;
+    /** 是否 @ 了某个用户/机器人 */
+    mentions: Array<{
+        key: string;
+        openId?: string;
+        name: string;
+    }>;
+    /** 收到事件的时间戳（毫秒） */
+    receivedAt: number;
+}
+/**
+ * 卡片按钮回调事件（业务层格式）
+ *
+ * 用户点击卡片上的 button（behaviors:[{type:'callback'}]) 时，飞书会推一个
+ * card.action.trigger 事件，dispatch 到这里。
+ */
+interface CardActionEvent {
+    /** 触发事件的 message_id（即卡片所在那条消息的 id） */
+    messageId: string;
+    /** chat id */
+    chatId: string;
+    /** 操作者的 open_id */
+    senderOpenId: string;
+    /**
+     * 按钮 value 字段——业务层自定义结构。
+     * 我们约定每个按钮都带 { action: 'model.set' | 'ws.use' | ..., ... }。
+     */
+    value: Record<string, unknown>;
+    /**
+     * 表单提交字段（仅 button 在 form 里点提交时有值）。
+     * 飞书 v2 表单：每个 input 的 name 属性 → 用户输入的 value。
+     */
+    formValue?: Record<string, unknown>;
+    /** 飞书发的 token（可用于在 30 分钟内更新原卡片，最多 2 次。当前未用，留给未来） */
+    token?: string;
+    /** 触发时间戳 */
+    receivedAt: number;
+}
+
+/**
+ * 飞书 SDK 封装
+ *
+ * 提供两个能力：
+ *   1. WebSocket 长连接事件监听（订阅 im.message.receive_v1 + card.action.trigger）
+ *   2. 飞书 OpenAPI 调用：发消息、发卡片、更新卡片、查机器人 open_id
+ *
+ * 与业务层之间通过 onMessage / onCardAction 回调解耦。
+ */
+
+interface LarkClientOptions {
+    appId: string;
+    appSecret: string;
+    logger: Logger;
+}
+declare class LarkClient {
+    readonly appId: string;
+    private readonly appSecret;
+    private readonly log;
+    readonly api: lark.Client;
+    private wsClient;
+    private botOpenIdCache;
+    constructor(opts: LarkClientOptions);
+    /**
+     * 启动 WebSocket 长连接，注册事件 handler：
+     *   - im.message.receive_v1：用户发的消息
+     *   - card.action.trigger：用户点了卡片上的按钮
+     */
+    startEventLoop(handlers: {
+        onMessage: (msg: IncomingMessage) => void | Promise<void>;
+        onCardAction?: (evt: CardActionEvent) => void | Promise<void>;
+        onReady?: () => void;
+        onReconnected?: () => void;
+    }): Promise<void>;
+    close(): void;
+    /**
+     * 查询当前机器人在租户里的 open_id（用来识别 @bot）。
+     * 应用启动时调用一次后缓存。
+     */
+    getBotOpenId(): Promise<string>;
+    /** 业务侧主动设置 botOpenId（一般从配置或第一次 @bot 学习而来）。 */
+    setBotOpenId(openId: string): void;
+    /**
+     * 发送一张飞书卡片（v2 协议）。
+     * 返回卡片所在消息的 message_id，后续用 patchCard 更新。
+     */
+    sendCard(chatId: string, cardJson: object): Promise<string>;
+    /**
+     * 回复一条消息（reply 卡片，让卡片挂在用户消息下面）。
+     */
+    replyCard(messageId: string, cardJson: object): Promise<string>;
+    /**
+     * 用 patch 接口整体替换卡片内容。
+     * 飞书消息卡片支持通过 `im/v1/messages/:message_id` PATCH 来更新内容，
+     * 内容必须是合法的卡片 JSON 字符串。
+     */
+    patchCard(messageId: string, cardJson: object): Promise<void>;
+    /** 发送纯文本消息（错误兜底用） */
+    sendText(chatId: string, text: string): Promise<string>;
+}
+
+declare const ChatSessionSchema: z.ZodObject<{
+    currentCwd: z.ZodString;
+    sessionsByCwd: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    lastActiveAt: z.ZodDefault<z.ZodNumber>;
+    /**
+     * per-chat idle watchdog 分钟数覆盖：
+     *   undefined → 用全局默认（preferences/kiro.idleTimeoutMinutes）
+     *   0         → 显式关闭
+     *   N>0       → 用 N 分钟
+     */
+    idleTimeoutMinutes: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    currentCwd: string;
+    sessionsByCwd: Record<string, string>;
+    lastActiveAt: number;
+    idleTimeoutMinutes?: number | undefined;
+}, {
+    currentCwd: string;
+    idleTimeoutMinutes?: number | undefined;
+    sessionsByCwd?: Record<string, string> | undefined;
+    lastActiveAt?: number | undefined;
+}>;
+type ChatSession = z.infer<typeof ChatSessionSchema>;
+declare class SessionStore {
+    /**
+     * 获取一个 chat 的会话状态；不存在则用 defaultCwd 初始化。
+     */
+    get(chatId: string, defaultCwd: string): Promise<ChatSession>;
+    /**
+     * 切换 chat 的当前 cwd。该 cwd 下若已有 kiro session 会被自动延用。
+     */
+    setCwd(chatId: string, cwd: string, defaultCwd: string): Promise<ChatSession>;
+    /**
+     * 关联当前 (chatId, cwd) 到一个 kiroSessionId（Kiro CLI 跑完返回的 sid）。
+     */
+    setKiroSession(chatId: string, cwd: string, kiroSessionId: string): Promise<void>;
+    /**
+     * 清空当前 cwd 下的 kiro session（用于 /new 命令）。
+     */
+    clearKiroSession(chatId: string, cwd: string): Promise<void>;
+    /**
+     * 获取当前 (chatId, cwd) 对应的 kiroSessionId（可能不存在）。
+     */
+    getKiroSession(chatId: string, cwd: string): Promise<string | undefined>;
+    /**
+     * 设置 chat 的 idle watchdog 阈值（分钟）。
+     *   - undefined：清除覆盖，回归全局默认
+     *   - 0：关闭
+     *   - N>0：用 N 分钟
+     */
+    setIdleTimeout(chatId: string, minutes: number | undefined, defaultCwd: string): Promise<void>;
+}
+
+declare class WorkspaceStore {
+    list(): Promise<Record<string, string>>;
+    get(name: string): Promise<string | undefined>;
+    save(name: string, absPath: string): Promise<void>;
+    remove(name: string): Promise<boolean>;
+}
+
+declare const ConfigSchema: z.ZodObject<{
+    lark: z.ZodObject<{
+        appId: z.ZodString;
+        appSecret: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        appId: string;
+        appSecret: string;
+    }, {
+        appId: string;
+        appSecret: string;
+    }>;
+    kiro: z.ZodDefault<z.ZodObject<{
+        binPath: z.ZodDefault<z.ZodString>;
+        trustedTools: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        /**
+         * 默认 idle watchdog（分钟）。0 = 关闭。
+         * stdout 连续这么久没新输出就当作 kiro-cli 假死，killTree。
+         * /timeout N 可以临时为某个 chat 覆盖。
+         */
+        idleTimeoutMinutes: z.ZodDefault<z.ZodNumber>;
+        model: z.ZodOptional<z.ZodString>;
+        agent: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        binPath: string;
+        trustedTools: string[];
+        timeoutMs: number;
+        idleTimeoutMinutes: number;
+        model?: string | undefined;
+        agent?: string | undefined;
+    }, {
+        binPath?: string | undefined;
+        trustedTools?: string[] | undefined;
+        timeoutMs?: number | undefined;
+        idleTimeoutMinutes?: number | undefined;
+        model?: string | undefined;
+        agent?: string | undefined;
+    }>>;
+    workspace: z.ZodDefault<z.ZodObject<{
+        defaultCwd: z.ZodDefault<z.ZodString>;
+        allowedRoots: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        defaultCwd: string;
+        allowedRoots: string[];
+    }, {
+        defaultCwd?: string | undefined;
+        allowedRoots?: string[] | undefined;
+    }>>;
+    access: z.ZodDefault<z.ZodObject<{
+        allowedUsers: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        allowedChats: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        admins: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        allowedUsers: string[];
+        allowedChats: string[];
+        admins: string[];
+    }, {
+        allowedUsers?: string[] | undefined;
+        allowedChats?: string[] | undefined;
+        admins?: string[] | undefined;
+    }>>;
+    preferences: z.ZodDefault<z.ZodObject<{
+        requireMentionInGroup: z.ZodDefault<z.ZodBoolean>;
+        cardUpdateIntervalMs: z.ZodDefault<z.ZodNumber>;
+        /** 启动时清理多少天之前的日志文件 */
+        logRetentionDays: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        requireMentionInGroup: boolean;
+        cardUpdateIntervalMs: number;
+        logRetentionDays: number;
+    }, {
+        requireMentionInGroup?: boolean | undefined;
+        cardUpdateIntervalMs?: number | undefined;
+        logRetentionDays?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    lark: {
+        appId: string;
+        appSecret: string;
+    };
+    kiro: {
+        binPath: string;
+        trustedTools: string[];
+        timeoutMs: number;
+        idleTimeoutMinutes: number;
+        model?: string | undefined;
+        agent?: string | undefined;
+    };
+    workspace: {
+        defaultCwd: string;
+        allowedRoots: string[];
+    };
+    access: {
+        allowedUsers: string[];
+        allowedChats: string[];
+        admins: string[];
+    };
+    preferences: {
+        requireMentionInGroup: boolean;
+        cardUpdateIntervalMs: number;
+        logRetentionDays: number;
+    };
+}, {
+    lark: {
+        appId: string;
+        appSecret: string;
+    };
+    kiro?: {
+        binPath?: string | undefined;
+        trustedTools?: string[] | undefined;
+        timeoutMs?: number | undefined;
+        idleTimeoutMinutes?: number | undefined;
+        model?: string | undefined;
+        agent?: string | undefined;
+    } | undefined;
+    workspace?: {
+        defaultCwd?: string | undefined;
+        allowedRoots?: string[] | undefined;
+    } | undefined;
+    access?: {
+        allowedUsers?: string[] | undefined;
+        allowedChats?: string[] | undefined;
+        admins?: string[] | undefined;
+    } | undefined;
+    preferences?: {
+        requireMentionInGroup?: boolean | undefined;
+        cardUpdateIntervalMs?: number | undefined;
+        logRetentionDays?: number | undefined;
+    } | undefined;
+}>;
+type Config = z.infer<typeof ConfigSchema>;
+/**
+ * 从磁盘加载配置；不存在则抛错（让 CLI 引导用户跑 init/wizard）。
+ */
+declare function loadConfig(): Config;
+/**
+ * 写入配置文件，权限 0600。
+ */
+declare function saveConfig(cfg: Config): void;
+/**
+ * 生成最小可用的配置模板，供 init 命令使用。
+ */
+declare function defaultConfig(appId: string, appSecret: string): Config;
+
+/**
+ * 消息总分发器
+ *
+ * 把一条飞书消息变成一个动作：
+ *   1. 访问控制校验（用户/群白名单、@bot 检测）
+ *   2. 下载图片/文件资源（如果有）
+ *   3. 解析斜杠命令
+ *   4. 路由到 commandHandler 或 kiroHandler
+ *   5. 更新卡片
+ *
+ * 跨 chat 并发不限（每个 chat 自己内部串行）。
+ */
+
+interface DispatcherOptions {
+    config: Config;
+    lark: LarkClient;
+    sessions: SessionStore;
+    workspaces: WorkspaceStore;
+    logger: Logger;
+    /** 当 /reconnect 命令触发时调用，由 bootstrap 注入 */
+    onReconnect?: () => Promise<void>;
+}
+declare class Dispatcher {
+    private config;
+    private readonly lark;
+    private readonly sessions;
+    private readonly workspaces;
+    private readonly log;
+    private readonly pipelines;
+    private readonly onReconnect?;
+    constructor(opts: DispatcherOptions);
+    private getPipeline;
+    /** eventId 去重缓存：飞书 at-least-once 投递保险 */
+    private readonly seenEventIds;
+    private readonly EVENT_TTL_MS;
+    /**
+     * rapid-fire 消息合并：同 chat 短时间连发时把多条消息拼成一次 Kiro 调用。
+     *
+     * 价值：用户在飞书 IM 里习惯连发短消息（"等等"、"还有"、"刚才那个改一下"），
+     * 不合并的话每条都跑一次 Kiro，浪费 token 还会被前面的 abort 打断；合并后
+     * 一次性给 Kiro 完整意图。
+     *
+     * 实现：每条消息进来先放 buffer，200ms 内有新消息就追加；到时一次性 submit。
+     *   - 第一条触发计时器、注册 buffer
+     *   - 后续消息往 buffer 里追加文本（+ 媒体路径）
+     *   - 200ms 静默期到 → flush，用第一条的 msg/eventId 作为 reply 锚点
+     */
+    private readonly mergeBuffers;
+    private readonly MERGE_WINDOW_MS;
+    private isDuplicate;
+    /**
+     * 主入口：处理一条飞书消息。
+     */
+    handle(msg: IncomingMessage): Promise<void>;
+    private workspaceNameOf;
+    /**
+     * 计算某个 chat 实际生效的 idle watchdog 分钟数。
+     *   - per-chat override 存在（包括 0）→ 优先用它
+     *   - 否则用 config.kiro.idleTimeoutMinutes
+     */
+    private effectiveIdleMinutes;
+    private handleTimeoutCmd;
+    /**
+     * /doctor [描述]
+     * 把最近 200 行结构化日志 + 用户描述拼成 prompt 喂给 Kiro 自诊断。
+     * 走标准 runKiroTask 流程，享受所有流式卡片和 watchdog。
+     */
+    private handleDoctorCmd;
+    /**
+     * /model         → 列出所有模型 + 当前选中（漂亮按钮卡片）
+     * /model <name>  → 切换模型，写入 config.json，立即生效
+     * /model auto    → 清除模型覆盖，回归 kiro-cli 默认（auto）
+     *
+     * 短名容错：/model sonnet-4.6 → 自动补 claude- 前缀
+     *
+     * 设计取舍：
+     *   - 切模型只改全局 config.json，不做 per-chat 覆盖（先做最少必要）
+     *   - 切完不需要 reconnect，下一条消息直接生效（spawn kiro-cli 时读最新 config）
+     */
+    private handleModelCmd;
+    /**
+     * 模型名解析：
+     *   - 列表里精确匹配 → 直接返回
+     *   - 列表里有 "claude-<name>" → 返回带前缀的全名（短名容错）
+     *   - 都不匹配 → 返回 undefined（让上层报错）
+     * 列表为空（fetch 失败）时直接返回原名，不阻塞。
+     */
+    private resolveModelName;
+    /**
+     * 发送一张飞书 v2 交互卡片（带按钮的那种）作为对原消息的回复。
+     * 跟 replyDoneCard 不同：不走 CardRenderer 的状态机，发一次就完事，
+     * 不会再 patch；按钮回调走 onCardAction 流程。
+     */
+    private sendInteractiveCard;
+    /**
+     * 命令型卡片的"先占位再 patch"模式。
+     *
+     * 用于命令本身需要做异步工作（spawn kiro-cli 等）才能算出最终卡片内容的场景：
+     *   1. 先用 placeholderCard 立刻 reply 出去，让用户看到反馈
+     *   2. 异步跑 buildFinalCard()
+     *   3. 用 patchCard 替换成最终卡片
+     *
+     * 失败时直接发 fallback 错误卡片，不让用户卡在 placeholder。
+     */
+    private sendInteractiveCardAsync;
+    /**
+     * 直接发卡片到 chatId（不 reply 任何特定消息）。
+     * cardAction handler 用这个——按钮触发时不 reply 那条卡片本身（嵌套体验差），
+     * 而是发新消息。
+     */
+    private sendCardToChat;
+    /**
+     * 处理用户点了卡片按钮的事件。
+     * value 约定字段：{ action: 'xxx.yyy', ...payload }
+     *
+     * 安全：button 触发的命令也会经过 admin 校验（调用 needAdminForAction）。
+     */
+    handleCardAction(evt: CardActionEvent): Promise<void>;
+    /** 哪些 action 是写操作，需要 admin */
+    private actionNeedsAdmin;
+    /**
+     * /config 命令：展示当前配置（只读卡片，admin 可见编辑按钮）
+     */
+    private handleConfigCmd;
+    /**
+     * 处理 config 表单提交。
+     *
+     * 流程：
+     *   1. 解析 form_value（用户输入的逗号分隔列表 / 整数 / yes/no）
+     *   2. 用 validateAccessChange 校验，防止把自己锁出去
+     *   3. patchAndSaveConfig 落盘 + 立即生效
+     *   4. 回一张确认卡片（同时显示新的 config view）
+     */
+    private handleConfigSubmit;
+    private replyErrorCard;
+    /**
+     * 把一条用户消息丢给 Kiro 处理。
+     *
+     * **包了一层 rapid-fire 合并**：先放 buffer，等 200ms 静默期再真正 submit；
+     * 期间若同 chat 又来新消息，就追加到同一个 buffer，不会触发 abort+rerun。
+     *
+     * 真正的 Kiro 调用在 executeKiroTask 里。
+     */
+    private runKiroTask;
+    /**
+     * flush 当前 chat 的合并 buffer：把累计的文本拼一起，调 executeKiroTask。
+     */
+    private flushMergeBuffer;
+    /**
+     * 真正把任务丢到 ChatPipeline 跑 Kiro 的实现（不含 rapid-fire 合并）。
+     * - 在 ChatPipeline 里跑（自动 preempt）
+     * - 用 RunCardController 流式刷新卡片（每个工具独立 panel）
+     * - mediaPaths 非空时，把绝对路径作为前缀加到 prompt 前面
+     * - perChatIdleMin 控制本次 idle watchdog 阈值
+     */
+    private executeKiroTask;
+}
+
+/**
+ * 单 chat 任务管线
+ *
+ * 一个飞书 chat 一个 ChatPipeline 实例。职责：
+ *   - 对该 chat 串行执行任务（同一时刻最多一个 Kiro 在跑）
+ *   - 新任务到来时打断旧任务（"preempt"）
+ *   - 提供 stop() 主动中止当前任务
+ */
+
+interface PipelineTask {
+    /** 任务 id（用于日志） */
+    id: string;
+    /** 真正干活的函数；接收 AbortSignal */
+    run: (signal: AbortSignal) => Promise<void>;
+}
+declare class ChatPipeline {
+    readonly chatId: string;
+    private readonly log;
+    private currentAbort;
+    private currentTaskId;
+    private currentPromise;
+    constructor(chatId: string, logger: Logger);
+    /**
+     * 提交新任务。
+     * 如果当前有任务在跑：
+     *   - 先发 abort 信号
+     *   - 等旧任务收尾（旧 run() 应该 catch AbortError 并 finalize 卡片）
+     *   - 再启动新任务
+     */
+    submit(task: PipelineTask): Promise<void>;
+    /** 主动中止当前任务（/stop 命令）。返回是否真的中止了某任务。 */
+    abortCurrent(): boolean;
+    hasActiveTask(): boolean;
+}
+
+interface RunOptions {
+    /** 用户消息（即喂给 kiro-cli 的 INPUT 参数） */
+    prompt: string;
+    /** 工作目录 */
+    cwd: string;
+    /** 续接的 session id；不传则新建会话 */
+    resumeId?: string | undefined;
+    /** kiro-cli 可执行文件，默认 'kiro-cli' */
+    binPath?: string;
+    /** 信任的工具集合 */
+    trustedTools?: string[];
+    /** 模型名（可选） */
+    model?: string | undefined;
+    /** Agent 名（可选） */
+    agent?: string | undefined;
+    /** 总超时毫秒 */
+    timeoutMs?: number;
+    /**
+     * 空闲 watchdog 阈值（毫秒）。
+     * 若 stdout 连续这么久没新输出就认为假死，杀掉子进程。
+     * 0 或不传 = 关闭 watchdog（仅依赖 timeoutMs）。
+     */
+    idleTimeoutMs?: number;
+    /**
+     * 流式文本回调；text 是已剥离 ANSI 的纯文本片段。
+     * 调用方拿到原始流后自行解析（用 createRunStreamParser），
+     * 不再由 runner 内部做 trace/正文分离。
+     */
+    onChunk?: (text: string) => void;
+    /** AbortSignal 用于外部打断 */
+    signal?: AbortSignal;
+}
+interface RunResult {
+    /** 完整回复（已剥离 ANSI） */
+    text: string;
+    /** kiro-cli 退出码 */
+    exitCode: number | null;
+    /** 跑完之后从 list-sessions 拿到的最新 session id（可能为 undefined） */
+    newSessionId?: string;
+    /** 是否被外部信号中止 */
+    aborted: boolean;
+    /** 是否因总超时被强杀 */
+    timedOut: boolean;
+    /** 是否因 idle watchdog 被强杀（超过 idleTimeoutMs 没新输出） */
+    idleTimedOut: boolean;
+}
+/**
+ * 跑一次 kiro-cli。流式回调和超时/打断都安全终止。
+ */
+declare function runKiro(opts: RunOptions): Promise<RunResult>;
+
+/**
+ * 全局日志器
+ * - 开发模式（TTY）用 pino-pretty 输出彩色易读日志
+ * - 生产模式输出 NDJSON，写入 ~/.lark-kiro-bridge/logs/YYYY-MM-DD.log
+ * - 启动时按 logRetentionDays（默认 7 天）清理旧日志
+ *   ENV LARK_KIRO_LOG_DAYS 可覆盖，便于不读 config 的场景
+ */
+
+declare function getLogger(): Logger;
+
+interface RunBridgeHandle {
+    /** 主动停止；返回 promise 在所有清理完成后 resolve */
+    stop: () => Promise<void>;
+}
+declare function runBridge(): Promise<RunBridgeHandle>;
+
+export { ChatPipeline, type Config, Dispatcher, LarkClient, SessionStore, WorkspaceStore, defaultConfig, getLogger, loadConfig, runBridge, runKiro, saveConfig };