@jesonliu/lark-claudecode-bridge 0.3.0

package/dist/executor/permission-gate.js

@@ -0,0 +1,66 @@
+// 权限闸：只读工具直通，写操作经 ask 回调询问（飞书卡片确认），带超时自动拒绝与会话级记忆
+import { randomUUID } from 'node:crypto';
+import { NOTIFY_TOOL_PREFIX } from './notify-server.js';
+// 会话内免询问的只读工具白名单（不含任何写文件/执行类工具）
+export const READ_ONLY_TOOLS = new Set([
+    'Read', 'Glob', 'Grep', 'LS', 'TodoRead', 'TodoWrite', 'WebFetch', 'WebSearch',
+]);
+// 超时默认 10 分钟：飞书端可能长时间无人点击卡片
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+// 内部哨兵：区分「超时拒绝」与「用户主动拒绝」，便于给出准确原因
+const TIMED_OUT = Symbol('timed-out');
+export class PermissionGate {
+    opts;
+    remembered = new Set();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async decide(toolName, input, workspaceName) {
+        if (READ_ONLY_TOOLS.has(toolName))
+            return { behavior: 'allow' };
+        // lcb-notify 通知工具直通：server 实例由 executeTask 闭包构造，chatId 硬绑定，
+        // 模型无法选择接收者（只能发到当前任务发起的聊天），无破坏性，逐张发图不应逐次弹确认卡。
+        // 用前缀匹配：后续往 notify server 新增工具自动直通。
+        if (toolName.startsWith(NOTIFY_TOOL_PREFIX))
+            return { behavior: 'allow' };
+        if (this.remembered.has(toolName))
+            return { behavior: 'allow' };
+        const req = {
+            requestId: randomUUID(),
+            toolName,
+            summary: typeof input.command === 'string' ? input.command
+                : typeof input.file_path === 'string' ? input.file_path
+                    : JSON.stringify(input).slice(0, 800),
+            workspaceName,
+        };
+        const timeoutMs = this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        // 持 timer handle：ask 及时答复后主动清理，避免常驻进程中每个已答复 decide 留一个最长 10 分钟的存活 timer
+        let timer;
+        const timeoutPromise = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
+            timer.unref();
+        });
+        let decision;
+        try {
+            decision = await Promise.race([this.opts.ask(req), timeoutPromise]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (decision === 'allow-session')
+            this.rememberSession(toolName);
+        if (decision === TIMED_OUT) {
+            return { behavior: 'deny', message: `确认超时（${Math.round(timeoutMs / 60000)} 分钟未响应），已自动拒绝 ${toolName}` };
+        }
+        if (decision === 'deny')
+            return { behavior: 'deny', message: `用户在飞书端拒绝了本次操作（${toolName}）` };
+        return { behavior: 'allow' };
+    }
+    rememberSession(toolName) {
+        this.remembered.add(toolName);
+    }
+    reset() {
+        this.remembered.clear();
+    }
+}
+//# sourceMappingURL=permission-gate.js.map

package/dist/executor/permission-gate.js.map

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

package/dist/gateway/card-builder.d.ts

@@ -0,0 +1,15 @@
+import type { ConfirmationRequest, PermissionDecision } from '../types.js';
+export interface ProgressState {
+    title: string;
+    status: string;
+    textTail: string;
+    toolLine: string;
+    startedAt: number;
+}
+export declare function buildTextCard(markdown: string): unknown;
+/** 图片卡片：caption（可选）显示在图片上方——逐张发图时带编号说明用 */
+export declare function buildImageCard(caption: string | undefined, imgKey: string): unknown;
+export declare function buildProgressCard(state: ProgressState): unknown;
+export declare function buildConfirmCard(req: ConfirmationRequest): unknown;
+export declare const DECISION_TEXT: Record<PermissionDecision, string>;
+export declare function buildConfirmResultCard(req: ConfirmationRequest, decision: PermissionDecision, byName: string): unknown;

package/dist/gateway/card-builder.js

@@ -0,0 +1,60 @@
+function card(elements) {
+    return { schema: '2.0', config: { update_multi: true }, body: { elements } };
+}
+function md(content) {
+    return { tag: 'markdown', content };
+}
+export function buildTextCard(markdown) {
+    return card([md(markdown)]);
+}
+/** 图片卡片：caption（可选）显示在图片上方——逐张发图时带编号说明用 */
+export function buildImageCard(caption, imgKey) {
+    const elements = [];
+    if (caption)
+        elements.push(md(caption));
+    elements.push({ tag: 'img', img_key: imgKey, alt: { tag: 'plain_text', content: caption ?? '图片' } });
+    return card(elements);
+}
+export function buildProgressCard(state) {
+    const elapsed = Math.max(0, Math.floor((Date.now() - state.startedAt) / 1000));
+    const lines = [`**${state.title}**`, ``, state.status, ``];
+    if (state.toolLine)
+        lines.push(`🔧 ${state.toolLine}`, ``);
+    if (state.textTail)
+        lines.push('---', state.textTail.slice(-1200)); // 只保留尾部，防爆卡片
+    lines.push(``, `<font color='grey'>⏱ 已运行 ${Math.floor(elapsed / 60)} 分 ${elapsed % 60} 秒</font>`);
+    return card([md(lines.join('\n'))]);
+}
+export function buildConfirmCard(req) {
+    const body = req.diff
+        ? `\`\`\`diff\n${req.diff.slice(0, 1500)}\n\`\`\``
+        : `\`\`\`\n${req.summary.slice(0, 1500)}\n\`\`\``;
+    const button = (decision) => ({
+        tag: 'button',
+        text: { tag: 'plain_text', content: decision === 'allow' ? '✅ 允许' : decision === 'deny' ? '❌ 拒绝' : '⏭ 本次会话不再询问' },
+        type: decision === 'allow' ? 'primary' : decision === 'deny' ? 'danger' : 'default',
+        behaviors: [{ type: 'callback', value: { requestId: req.requestId, decision } }],
+    });
+    return card([
+        md(`**🔐 Claude 请求执行操作**\n\n工具: \`${req.toolName}\`　工作区: \`${req.workspaceName}\`\n${body}`),
+        {
+            // 卡片 V2 已废弃 tag:'action' 交互模块，改用 column_set 分栏实现按钮并排
+            tag: 'column_set',
+            flex_mode: 'flow',
+            columns: ['allow', 'deny', 'allow-session'].map((decision) => ({
+                tag: 'column', width: 'auto', weight: 1, vertical_align: 'top',
+                elements: [button(decision)],
+            })),
+        },
+    ]);
+}
+export const DECISION_TEXT = {
+    allow: '✅ 已允许',
+    deny: '❌ 已拒绝',
+    'allow-session': '⏭ 本次会话不再询问',
+};
+export function buildConfirmResultCard(req, decision, byName) {
+    // 摘要截断与确认卡一致（1500）：点击瞬间回调响应内联换卡，摘要突然缩水会被用户看到
+    return card([md(`**🔐 Claude 请求执行操作**\n\n工具: \`${req.toolName}\`　工作区: \`${req.workspaceName}\`\n\`\`\`\n${req.summary.slice(0, 1500)}\n\`\`\`\n\n${DECISION_TEXT[decision]}（由 ${byName} 操作）`)]);
+}
+//# sourceMappingURL=card-builder.js.map

package/dist/gateway/card-builder.js.map

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

package/dist/gateway/feishu-gateway.d.ts

@@ -0,0 +1,164 @@
+import type { FeishuAppConfig, GatewayHandlers, IncomingMessage } from '../types.js';
+/** SDK 形状：仅用到 WSClient/EventDispatcher/Client/Domain 四个导出，测试注入假对象时按此约束 */
+export interface FeishuSdk {
+    WSClient: new (params: {
+        appId: string;
+        appSecret?: string;
+        domain?: unknown;
+        loggerLevel?: number;
+    }) => {
+        start(params: {
+            eventDispatcher: unknown;
+        }): Promise<void>;
+        /** 优雅关闭长连接（node-sdk 1.73.0 已实现：终止重连循环并关 socket） */
+        close(params?: {
+            force?: boolean;
+        }): void;
+    };
+    EventDispatcher: new (params: Record<string, never>) => {
+        register<T extends Record<string, (data: never) => unknown>>(handles: T): unknown;
+    };
+    Client: new (params: {
+        appId: string;
+        appSecret?: string;
+        domain?: unknown;
+        loggerLevel?: number;
+    }) => {
+        im: {
+            message: {
+                create(payload: {
+                    params: {
+                        receive_id_type: 'chat_id';
+                    };
+                    data: {
+                        receive_id: string;
+                        msg_type: string;
+                        content: string;
+                    };
+                }): Promise<{
+                    code?: number;
+                    msg?: string;
+                    data?: {
+                        message_id?: string;
+                    };
+                }>;
+                patch(payload: {
+                    path: {
+                        message_id: string;
+                    };
+                    data: {
+                        content: string;
+                    };
+                }): Promise<{
+                    code?: number;
+                    msg?: string;
+                }>;
+            };
+            image: {
+                create(payload: {
+                    data: {
+                        image_type: 'message';
+                        image: NodeJS.ReadableStream;
+                    };
+                }): Promise<{
+                    image_key?: string;
+                } | null>;
+            };
+            file: {
+                create(payload: {
+                    data: {
+                        file_type: 'opus' | 'mp4' | 'pdf' | 'doc' | 'xls' | 'ppt' | 'stream';
+                        file_name: string;
+                        file: NodeJS.ReadableStream;
+                    };
+                }): Promise<{
+                    file_key?: string;
+                } | null>;
+            };
+        };
+        request(payload: {
+            method: string;
+            url: string;
+        }): Promise<{
+            code?: number;
+            msg?: string;
+            bot?: {
+                open_id?: string;
+            };
+        }>;
+    };
+    Domain: {
+        Feishu: unknown;
+        Lark: unknown;
+    };
+}
+/** 去 @机器人 前缀（飞书群聊 @ 在文本中渲染为 @_user_N 占位） */
+export declare function stripMention(text: string): string;
+/**
+ * 解析 im.message.receive_v1 事件为 IncomingMessage。
+ *
+ * 群聊 @检测：botOpenId（机器人 open_id）可用时按 mentions 数组精确匹配——
+ * 占位符/mentions 非空无法区分 @机器人 vs @普通人（群里 @任何人都命中，会被误当任务执行）；
+ * botOpenId 缺失（获取失败/未提供）时退化为旧的占位符 + mentions 非空判定，
+ * 但 strictGroupMention=true（多机器人部署）时宁丢不猜——同群多机器人下占位符退化判定
+ * 会让每个机器人都被触发（重复执行），丢弃比误执行安全；p2p 不依赖 @ 检测不受影响。
+ *
+ * ⚠️ 数据结构说明（与 brief 参考实现不同）：node-sdk 的 EventDispatcher 回调收到的是
+ * RequestHandle.parse() 展平后的数据——v2 事件 {schema, header, event} 被解包为
+ * 顶层 {...header, ...event}，即顶层 {sender, message}；而非 {event: {message, sender}}。
+ * 本函数以展平结构为主，同时兼容 {event: {...}} 包裹形态（原始事件体直投）。
+ * 结构不合法一律返回 null，绝不抛异常。
+ */
+export declare function parseIncomingMessage(event: unknown, botOpenId?: string, opts?: {
+    strictGroupMention?: boolean;
+}): IncomingMessage | null;
+export declare class FeishuGateway {
+    private client;
+    private sdk;
+    private cfg;
+    private ws?;
+    private log;
+    private strictGroupMention;
+    constructor(cfg: FeishuAppConfig, deps?: {
+        sdk?: FeishuSdk;
+        /** 日志出口（多 app 部署时注入带 [app:name] 前缀的 logger 以区分机器人） */
+        log?: {
+            warn: (...a: unknown[]) => void;
+            error: (...a: unknown[]) => void;
+        };
+        /** 严格群聊 @ 模式：botOpenId 不可用时丢弃群消息而非退化猜测（多机器人同群防双触发） */
+        strictGroupMention?: boolean;
+    });
+    /**
+     * 拉取机器人 open_id：群聊 @检测的精确匹配依据。
+     * SDK 1.73.0 未封装「获取机器人信息」接口（bot 命名空间仅 v4.bot.search），
+     * 经通用 request() 调 GET /open-apis/bot/v3/info。失败不阻断启动，
+     * 仅 warn 一次并让群聊 @检测退化为占位符匹配（严格模式下群消息将被丢弃）。
+     */
+    private fetchBotOpenId;
+    /** 建立 WS 长连接并注册事件分发（im.message.receive_v1 / card.action.trigger） */
+    start(handlers: GatewayHandlers): Promise<void>;
+    /** 优雅关闭长连接（SIGINT/SIGTERM 时逐个 app 调用）；未 start 时为 no-op */
+    close(): void;
+    /** 发送卡片消息，返回 message_id */
+    sendCard(chatId: string, card: unknown): Promise<string>;
+    /** 以卡片形态发送 markdown 文本 */
+    sendText(chatId: string, markdown: string): Promise<string>;
+    /** 更新已发送卡片（流式进度刷新） */
+    updateCard(messageId: string, card: unknown): Promise<void>;
+    /**
+     * 上传图片并发送带 caption 的卡片（caption 显示在图片上方，逐张发图带编号说明用）。
+     * 卡片形态发送失败时降级为「caption 文本卡 + 纯图片消息」两条，保证图片必达
+     * （img 卡片元素对 message 型 image_key 的兼容性异常兜底）。
+     */
+    sendImage(chatId: string, filePath: string, caption?: string): Promise<string>;
+    /**
+     * 上传并发送文件：图片扩展名走 im.image.create（返回顶层 image_key），
+     * 其余走 im.file.create（返回顶层 file_key）。
+     * ⚠️ 与 brief 参考实现不同：这两个上传接口的 SDK 封装比普通接口多拆一层，
+     * 返回 {image_key} / {file_key} 顶层对象（或 null），不存在 res.data 包装。
+     * 上传与发消息两步都校验关键返回值——SDK 业务级失败（HTTP 200 + code!=0）不抛错，
+     * 不校验会静默 resolve，用户收不到文件且无任何报错。
+     */
+    uploadAndSendFile(chatId: string, filePath: string): Promise<void>;
+}

package/dist/gateway/feishu-gateway.js

@@ -0,0 +1,249 @@
+import * as realSdk from '@larksuiteoapi/node-sdk';
+import { createReadStream } from 'node:fs';
+import { extname, basename } from 'node:path';
+import { buildImageCard, buildTextCard } from './card-builder.js';
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif']);
+/** 去 @机器人 前缀（飞书群聊 @ 在文本中渲染为 @_user_N 占位） */
+export function stripMention(text) {
+    return text.replace(/@_user_\d+\s*/g, '').trim();
+}
+/**
+ * 解析 im.message.receive_v1 事件为 IncomingMessage。
+ *
+ * 群聊 @检测：botOpenId（机器人 open_id）可用时按 mentions 数组精确匹配——
+ * 占位符/mentions 非空无法区分 @机器人 vs @普通人（群里 @任何人都命中，会被误当任务执行）；
+ * botOpenId 缺失（获取失败/未提供）时退化为旧的占位符 + mentions 非空判定，
+ * 但 strictGroupMention=true（多机器人部署）时宁丢不猜——同群多机器人下占位符退化判定
+ * 会让每个机器人都被触发（重复执行），丢弃比误执行安全；p2p 不依赖 @ 检测不受影响。
+ *
+ * ⚠️ 数据结构说明（与 brief 参考实现不同）：node-sdk 的 EventDispatcher 回调收到的是
+ * RequestHandle.parse() 展平后的数据——v2 事件 {schema, header, event} 被解包为
+ * 顶层 {...header, ...event}，即顶层 {sender, message}；而非 {event: {message, sender}}。
+ * 本函数以展平结构为主，同时兼容 {event: {...}} 包裹形态（原始事件体直投）。
+ * 结构不合法一律返回 null，绝不抛异常。
+ */
+export function parseIncomingMessage(event, botOpenId, opts = {}) {
+    try {
+        if (event === null || typeof event !== 'object')
+            return null;
+        const raw = event;
+        const payload = raw.message || raw.sender ? raw : raw.event;
+        const m = payload?.message;
+        if (!m?.chat_id || !m.message_id || m.message_type !== 'text')
+            return null;
+        const text = JSON.parse(m.content ?? '{}').text ?? '';
+        if (!text.trim())
+            return null;
+        const isGroup = m.chat_type !== 'p2p';
+        if (isGroup) {
+            if (botOpenId) {
+                // 精确判定：mentions 中存在 open_id === 机器人 open_id 的条目才算 @机器人
+                const mentionsBot = (m.mentions ?? []).some((t) => t.id?.open_id === botOpenId);
+                if (!mentionsBot)
+                    return null;
+            }
+            else if (opts.strictGroupMention) {
+                // 严格模式：无法精确判定 @ 目标时直接丢弃（多机器人同群防双触发）
+                return null;
+            }
+            else {
+                // 退化判定：文本里渲染为 @_user_N 占位；mentions 数组兜底
+                //（部分客户端形态下占位符缺失但 mentions 存在）
+                const mentionedInText = /@_user_\d+/.test(text);
+                const hasMention = mentionedInText || (m.mentions?.length ?? 0) > 0;
+                if (!hasMention)
+                    return null;
+            }
+        }
+        const userId = payload?.sender?.sender_id?.open_id;
+        if (!userId)
+            return null;
+        return {
+            chatId: m.chat_id,
+            chatType: isGroup ? 'group' : 'p2p',
+            userId,
+            text: stripMention(text),
+            messageId: m.message_id,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+const VALID_DECISIONS = new Set(['allow', 'deny', 'allow-session']);
+/** 解析 card.action.trigger 回调；不完整或 decision 不在合法枚举内返回 null */
+function parseCardAction(data) {
+    try {
+        if (data === null || typeof data !== 'object')
+            return null;
+        const d = data;
+        const value = d.action?.value;
+        // decision 必须严格匹配枚举：畸形字符串（如 'ALLOW'）不能流入 CardActionValue.decision
+        if (!value?.requestId || typeof value.decision !== 'string' || !VALID_DECISIONS.has(value.decision) || !d.operator?.open_id)
+            return null;
+        return {
+            value: { requestId: value.requestId, decision: value.decision },
+            operatorId: d.operator.open_id,
+            openMessageId: d.context?.open_message_id ?? d.open_message_id ?? '',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export class FeishuGateway {
+    client;
+    sdk;
+    cfg;
+    ws;
+    log;
+    strictGroupMention;
+    constructor(cfg, deps = {}) {
+        this.cfg = cfg;
+        this.sdk = deps.sdk ?? realSdk;
+        const tag = `[gateway:${cfg.name ?? cfg.appId}]`;
+        this.log = deps.log ?? {
+            warn: (...a) => console.warn(tag, ...a),
+            error: (...a) => console.error(tag, ...a),
+        };
+        this.strictGroupMention = deps.strictGroupMention ?? false;
+        const domain = cfg.domain === 'lark' ? this.sdk.Domain.Lark : this.sdk.Domain.Feishu;
+        this.client = new this.sdk.Client({ appId: cfg.appId, appSecret: cfg.appSecret, domain });
+    }
+    /**
+     * 拉取机器人 open_id：群聊 @检测的精确匹配依据。
+     * SDK 1.73.0 未封装「获取机器人信息」接口（bot 命名空间仅 v4.bot.search），
+     * 经通用 request() 调 GET /open-apis/bot/v3/info。失败不阻断启动，
+     * 仅 warn 一次并让群聊 @检测退化为占位符匹配（严格模式下群消息将被丢弃）。
+     */
+    async fetchBotOpenId() {
+        try {
+            const res = await this.client.request({ method: 'GET', url: '/open-apis/bot/v3/info' });
+            const openId = res?.bot?.open_id;
+            if (openId)
+                return openId;
+            this.log.warn(`机器人信息未返回 open_id：${JSON.stringify(res)}，群聊 @检测${this.strictGroupMention ? '严格模式：群消息将被丢弃' : '退化为占位符匹配'}`);
+        }
+        catch (e) {
+            this.log.warn('获取机器人 open_id 失败（不影响启动），群聊 @检测' + (this.strictGroupMention ? '严格模式：群消息将被丢弃' : '退化为占位符匹配') + '：', e);
+        }
+        return undefined;
+    }
+    /** 建立 WS 长连接并注册事件分发（im.message.receive_v1 / card.action.trigger） */
+    async start(handlers) {
+        const botOpenId = await this.fetchBotOpenId();
+        const ws = new this.sdk.WSClient({ appId: this.cfg.appId, appSecret: this.cfg.appSecret });
+        this.ws = ws;
+        const dispatcher = new this.sdk.EventDispatcher({}).register({
+            'im.message.receive_v1': async (data) => {
+                const msg = parseIncomingMessage(data, botOpenId, { strictGroupMention: this.strictGroupMention });
+                if (msg)
+                    await handlers.onMessage(msg);
+            },
+            // 卡片回调必须返回对象（飞书 SDK 契约：返回值经 WS 回传，undefined 会被当异常）；
+            // handler 返回了响应体（如 toast / 内联换卡 card）则透传，否则返回 {}。
+            // 畸形回调（parseCardAction 为 null）有意静默返回 {}：无有效操作对象，弹 toast 无服务意义
+            'card.action.trigger': async (data) => {
+                const action = parseCardAction(data);
+                const ret = action ? await handlers.onCardAction(action) : undefined;
+                return ret ?? {};
+            },
+        });
+        await ws.start({ eventDispatcher: dispatcher });
+    }
+    /** 优雅关闭长连接（SIGINT/SIGTERM 时逐个 app 调用）；未 start 时为 no-op */
+    close() {
+        try {
+            this.ws?.close();
+        }
+        catch {
+            // best effort：关闭失败不阻断其余连接的关闭
+        }
+    }
+    /** 发送卡片消息，返回 message_id */
+    async sendCard(chatId, card) {
+        const res = await this.client.im.message.create({
+            params: { receive_id_type: 'chat_id' },
+            data: { receive_id: chatId, msg_type: 'interactive', content: JSON.stringify(card) },
+        });
+        if (!res.data?.message_id)
+            throw new Error(`发送卡片失败: ${JSON.stringify(res)}`);
+        return res.data.message_id;
+    }
+    /** 以卡片形态发送 markdown 文本 */
+    async sendText(chatId, markdown) {
+        return this.sendCard(chatId, buildTextCard(markdown));
+    }
+    /** 更新已发送卡片（流式进度刷新） */
+    async updateCard(messageId, card) {
+        await this.client.im.message.patch({ path: { message_id: messageId }, data: { content: JSON.stringify(card) } });
+    }
+    /**
+     * 上传图片并发送带 caption 的卡片（caption 显示在图片上方，逐张发图带编号说明用）。
+     * 卡片形态发送失败时降级为「caption 文本卡 + 纯图片消息」两条，保证图片必达
+     * （img 卡片元素对 message 型 image_key 的兼容性异常兜底）。
+     */
+    async sendImage(chatId, filePath, caption) {
+        const up = await this.client.im.image.create({
+            data: { image_type: 'message', image: createReadStream(filePath) },
+        });
+        const imageKey = up?.image_key;
+        if (!imageKey)
+            throw new Error(`上传图片失败: ${JSON.stringify(up)}`);
+        try {
+            return await this.sendCard(chatId, buildImageCard(caption, imageKey));
+        }
+        catch (e) {
+            this.log.warn('图片卡片发送失败，降级为说明文本 + 图片消息两条：', e);
+            if (caption)
+                await this.sendText(chatId, caption).catch(() => { });
+            const res = await this.client.im.message.create({
+                params: { receive_id_type: 'chat_id' },
+                data: { receive_id: chatId, msg_type: 'image', content: JSON.stringify({ image_key: imageKey }) },
+            });
+            if (!res.data?.message_id)
+                throw new Error(`发送图片消息失败: ${JSON.stringify(res)}`);
+            return res.data.message_id;
+        }
+    }
+    /**
+     * 上传并发送文件：图片扩展名走 im.image.create（返回顶层 image_key），
+     * 其余走 im.file.create（返回顶层 file_key）。
+     * ⚠️ 与 brief 参考实现不同：这两个上传接口的 SDK 封装比普通接口多拆一层，
+     * 返回 {image_key} / {file_key} 顶层对象（或 null），不存在 res.data 包装。
+     * 上传与发消息两步都校验关键返回值——SDK 业务级失败（HTTP 200 + code!=0）不抛错，
+     * 不校验会静默 resolve，用户收不到文件且无任何报错。
+     */
+    async uploadAndSendFile(chatId, filePath) {
+        const ext = extname(filePath).toLowerCase();
+        if (IMAGE_EXT.has(ext)) {
+            const up = await this.client.im.image.create({
+                data: { image_type: 'message', image: createReadStream(filePath) },
+            });
+            const imageKey = up?.image_key;
+            if (!imageKey)
+                throw new Error(`上传图片失败: ${JSON.stringify(up)}`);
+            const res = await this.client.im.message.create({
+                params: { receive_id_type: 'chat_id' },
+                data: { receive_id: chatId, msg_type: 'image', content: JSON.stringify({ image_key: imageKey }) },
+            });
+            if (!res.data?.message_id)
+                throw new Error(`发送图片消息失败: ${JSON.stringify(res)}`);
+        }
+        else {
+            const up = await this.client.im.file.create({
+                data: { file_type: 'stream', file_name: basename(filePath), file: createReadStream(filePath) },
+            });
+            const fileKey = up?.file_key;
+            if (!fileKey)
+                throw new Error(`上传文件失败: ${JSON.stringify(up)}`);
+            const res = await this.client.im.message.create({
+                params: { receive_id_type: 'chat_id' },
+                data: { receive_id: chatId, msg_type: 'file', content: JSON.stringify({ file_key: fileKey }) },
+            });
+            if (!res.data?.message_id)
+                throw new Error(`发送文件消息失败: ${JSON.stringify(res)}`);
+        }
+    }
+}
+//# sourceMappingURL=feishu-gateway.js.map

package/dist/gateway/feishu-gateway.js.map

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

package/dist/gateway/progress-card.d.ts

@@ -0,0 +1,34 @@
+export interface CardSender {
+    sendCard(card: unknown): Promise<string>;
+    updateCard(messageId: string, card: unknown): Promise<void>;
+}
+export declare class ProgressCard {
+    private sender;
+    private opts;
+    private messageId?;
+    private buffer;
+    private state;
+    private flushTimer?;
+    private heartbeatTimer?;
+    private lastActivityAt;
+    private done;
+    private flushChain;
+    private dirty;
+    private flushing;
+    constructor(sender: CardSender, title: string, opts?: {
+        flushIntervalMs?: number;
+        idleHeartbeatMs?: number;
+    });
+    start(): Promise<void>;
+    appendText(delta: string): void;
+    toolStart(name: string, summary: string): void;
+    toolResult(name: string, ok: boolean): void;
+    setStatus(status: string): void;
+    finish(summary: string): Promise<void>;
+    /**
+     * 串行化 flush：所有更新走同一条 promise 链按发起顺序落地。
+     * - in-flight 中再来请求 → 标记 dirty，本轮落地后自动补刷一次（带上最新 state）；
+     * - finish 的终态 flush 也入链，天然排在先前挂起的更新之后。
+     */
+    private flush;
+}