lark-remote 0.1.0

package/dist/card/bash-card-session.d.ts

@@ -0,0 +1,78 @@
+import { CardSession, type CardChannel, type StreamSettleResult } from './card-session.js';
+import { type BashState, type BashRenderOptions } from './bash-renderer.js';
+/**
+ * Store-time 输出上限（字符，P1-3 层①）。§P1-3 建议「store-time 截断，
+ * 保留尾部，上限如 24~64KB」——取区间下界 24_000 字符（字符上限 ×4 字节最坏
+ * ~96KB/字段）。渲染层本就只展示尾部（bash-renderer 截断到 12KB 字节），store 截断
+ * 不影响显示内容，只保证内存有界：!yes / !cat 大文件不再把全部输出驻留在 session
+ * state 与 bridge 局部变量。
+ */
+export declare const BASH_OUTPUT_STORE_CAP = 24000;
+/**
+ * Store-time 截断入口（P1-3 层①/层④共用）。bridge 本地 output/stderr 与 session
+ * state 都走它，保证任意路径驻留的字符串 ≤ BASH_OUTPUT_STORE_CAP 字符。
+ * 调用方传入的 value 通常已 ≤ CAP（增量场景 output 恒 ≤ CAP，+chunk 后 ≤ CAP+chunk），
+ * slice(-CAP) 成本 O(CAP+chunk)，不会把 O(n²) 截断问题带回桥接循环。
+ */
+export declare function capBashOutput(value: string): string;
+/**
+ * Streaming card session for `!` bash commands — the bash analogue of
+ * RunCardSession. Holds a single BashState, renders renderBashCard, and
+ * patches ONE card via connector.streamCard across the run's lifetime
+ * (initial running → output updates → terminal), instead of sending many
+ * independent cards.
+ */
+export declare class BashCardSession extends CardSession<BashState, BashRenderOptions> {
+    /**
+     * P1-3 层③：push 合批窗口（ms），与 RunCardSession 同语义。连续 update 各触发
+     * 一次全卡 render + patch 是 PATCH 风暴主源；窗口内多个事件复用同一次延迟 flush。
+     * 窗口大小可通过 constructor 覆盖（测试用小窗口/0 禁用）。
+     */
+    private readonly coalesceMs;
+    private flushTimer;
+    private flushInFlight;
+    /** in-flight flush 期间到达的 update 标记：flush 完成后需重新调度（防 stale 帧）。 */
+    private pendingReschedule;
+    /** 当前 in-flight flush 的 promise：finish 在终态 patch 前 await 它保证顺序。 */
+    private flushP;
+    constructor(opts: {
+        connector: CardChannel;
+        chatId: string;
+        replyTo?: string;
+        runId: string;
+        command: string;
+        renderOptions?: BashRenderOptions;
+        startTimeoutMs?: number;
+        settleTimeoutMs?: number;
+        /** update 合批窗口，默认 100ms（0 = 禁用合批，每 update 立即 flush）。 */
+        coalesceMs?: number;
+    });
+    protected get logPrefix(): string;
+    protected get errorPrefix(): string;
+    protected renderCard(state: BashState, options: BashRenderOptions): object;
+    protected hasOwnBudgetProtection(): boolean;
+    /** Patch the card with updated bash state (e.g. new stdout/stderr). */
+    update(patch: Partial<BashState>): Promise<void>;
+    /** Transition to a terminal state and patch the card. */
+    finish(terminal: Exclude<BashState['terminal'], 'running'>, meta?: {
+        exitCode?: number | null;
+        stderr?: string;
+        output?: string;
+    }): Promise<void>;
+    /**
+     * 调度一次延迟 flush：已有 pending 调度则复用（合批核心）；flushInFlight 期间
+     * 不再起 timer（防重入叠加），但置 pendingReschedule 让 in-flight 完成后补渲染。
+     */
+    private scheduleFlush;
+    /** 执行一次 render + updateCard（合批窗口到期或 finish 即时 flush 时调用）。 */
+    private flush;
+    /** 取消待 flush 的合批调度（finish/settle 前清理，避免延迟 update 与终态竞争）。 */
+    private cancelPendingFlush;
+    /** settle 前兜底取消合批调度，避免 release 后 dangling timer 更新已释放的 stream。 */
+    settle(): Promise<StreamSettleResult>;
+    /**
+     * 合并 patch 并对 output/stderr 做 store-time 截断（P1-3 层①）。
+     * 截断发生在入口（store 时），渲染层无需再为大 state 付代价。
+     */
+    private applyCap;
+}

package/dist/card/bash-card-session.js

@@ -0,0 +1,174 @@
+import { CardSession } from './card-session.js';
+import { renderBashCard } from './bash-renderer.js';
+/**
+ * Store-time 输出上限（字符，P1-3 层①）。§P1-3 建议「store-time 截断，
+ * 保留尾部，上限如 24~64KB」——取区间下界 24_000 字符（字符上限 ×4 字节最坏
+ * ~96KB/字段）。渲染层本就只展示尾部（bash-renderer 截断到 12KB 字节），store 截断
+ * 不影响显示内容，只保证内存有界：!yes / !cat 大文件不再把全部输出驻留在 session
+ * state 与 bridge 局部变量。
+ */
+export const BASH_OUTPUT_STORE_CAP = 24_000;
+/** 字符级 tail 保留（与 run-state.keepLatest 的 slice(-maxChars) 语义一致）。 */
+function keepTail(value, maxChars) {
+    return value.length <= maxChars ? value : value.slice(-maxChars);
+}
+/**
+ * Store-time 截断入口（P1-3 层①/层④共用）。bridge 本地 output/stderr 与 session
+ * state 都走它，保证任意路径驻留的字符串 ≤ BASH_OUTPUT_STORE_CAP 字符。
+ * 调用方传入的 value 通常已 ≤ CAP（增量场景 output 恒 ≤ CAP，+chunk 后 ≤ CAP+chunk），
+ * slice(-CAP) 成本 O(CAP+chunk)，不会把 O(n²) 截断问题带回桥接循环。
+ */
+export function capBashOutput(value) {
+    return keepTail(value, BASH_OUTPUT_STORE_CAP);
+}
+/**
+ * Streaming card session for `!` bash commands — the bash analogue of
+ * RunCardSession. Holds a single BashState, renders renderBashCard, and
+ * patches ONE card via connector.streamCard across the run's lifetime
+ * (initial running → output updates → terminal), instead of sending many
+ * independent cards.
+ */
+export class BashCardSession extends CardSession {
+    /**
+     * P1-3 层③：push 合批窗口（ms），与 RunCardSession 同语义。连续 update 各触发
+     * 一次全卡 render + patch 是 PATCH 风暴主源；窗口内多个事件复用同一次延迟 flush。
+     * 窗口大小可通过 constructor 覆盖（测试用小窗口/0 禁用）。
+     */
+    coalesceMs;
+    flushTimer;
+    flushInFlight = false;
+    /** in-flight flush 期间到达的 update 标记：flush 完成后需重新调度（防 stale 帧）。 */
+    pendingReschedule = false;
+    /** 当前 in-flight flush 的 promise：finish 在终态 patch 前 await 它保证顺序。 */
+    flushP;
+    constructor(opts) {
+        super({
+            runId: opts.runId,
+            terminal: 'running',
+            output: '',
+            stderr: '',
+            exitCode: null,
+            command: opts.command,
+        }, {
+            connector: opts.connector,
+            chatId: opts.chatId,
+            replyTo: opts.replyTo,
+            renderOptions: opts.renderOptions,
+            startTimeoutMs: opts.startTimeoutMs,
+            settleTimeoutMs: opts.settleTimeoutMs,
+        });
+        this.coalesceMs = opts.coalesceMs ?? 100;
+    }
+    get logPrefix() {
+        return '[bash-card]';
+    }
+    get errorPrefix() {
+        return 'bash card';
+    }
+    renderCard(state, options) {
+        return renderBashCard(state, options);
+    }
+    hasOwnBudgetProtection() {
+        // renderBashCard 自带 stringify 级 degraded/extreme fallback 预算保护
+        // （与 renderRunCard 对称），保证返回卡 ≤28KB 且保留 command/exitCode。
+        // enforceCardBudget 是会话事件面板专用的静态裁剪层，对 bash 卡的普通
+        // markdownDiv output 是 misfit（超限时极端降级丢 command/exitCode），bash
+        // 卡应跳过它，靠自身 renderer 保护。
+        return true;
+    }
+    /** Patch the card with updated bash state (e.g. new stdout/stderr). */
+    async update(patch) {
+        this.state = this.applyCap(patch);
+        if (this.coalesceMs <= 0) {
+            await this.flush();
+            return;
+        }
+        this.scheduleFlush();
+    }
+    /** Transition to a terminal state and patch the card. */
+    async finish(terminal, meta = {}) {
+        this.cancelPendingFlush();
+        // 若有 in-flight flush 正在 await updateCard，必须等它完成后再发终态 patch，
+        // 保证顺序（pre-terminal 先落地 → terminal 后落地 → terminal 胜出）。
+        if (this.flushP)
+            await this.flushP;
+        this.state = {
+            ...this.state,
+            terminal,
+            ...(meta.exitCode !== undefined ? { exitCode: meta.exitCode } : {}),
+            ...(meta.stderr !== undefined ? { stderr: capBashOutput(meta.stderr) } : {}),
+            ...(meta.output !== undefined ? { output: capBashOutput(meta.output) } : {}),
+        };
+        await this.updateCard();
+        this.release();
+    }
+    /**
+     * 调度一次延迟 flush：已有 pending 调度则复用（合批核心）；flushInFlight 期间
+     * 不再起 timer（防重入叠加），但置 pendingReschedule 让 in-flight 完成后补渲染。
+     */
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        if (this.flushInFlight) {
+            this.pendingReschedule = true;
+            return;
+        }
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = undefined;
+            void this.flush();
+        }, this.coalesceMs);
+    }
+    /** 执行一次 render + updateCard（合批窗口到期或 finish 即时 flush 时调用）。 */
+    async flush() {
+        if (this.flushInFlight)
+            return;
+        // 终态守卫：finish 已把 state 转终态后，in-flight/延迟 flush 不再用旧 state patch
+        if (this.state.terminal !== 'running')
+            return;
+        this.flushInFlight = true;
+        const flushPromise = (async () => {
+            try {
+                await this.updateCard();
+            }
+            finally {
+                this.flushInFlight = false;
+                this.flushP = undefined;
+                // in-flight 期间若有 update 到达（pendingReschedule），重新调度一次渲染
+                if (this.pendingReschedule) {
+                    this.pendingReschedule = false;
+                    this.scheduleFlush();
+                }
+            }
+        })();
+        this.flushP = flushPromise;
+        return flushPromise;
+    }
+    /** 取消待 flush 的合批调度（finish/settle 前清理，避免延迟 update 与终态竞争）。 */
+    cancelPendingFlush() {
+        this.pendingReschedule = false;
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+            return true;
+        }
+        return false;
+    }
+    /** settle 前兜底取消合批调度，避免 release 后 dangling timer 更新已释放的 stream。 */
+    async settle() {
+        this.cancelPendingFlush();
+        return super.settle();
+    }
+    /**
+     * 合并 patch 并对 output/stderr 做 store-time 截断（P1-3 层①）。
+     * 截断发生在入口（store 时），渲染层无需再为大 state 付代价。
+     */
+    applyCap(patch) {
+        return {
+            ...this.state,
+            ...patch,
+            ...(patch.output !== undefined ? { output: capBashOutput(patch.output) } : {}),
+            ...(patch.stderr !== undefined ? { stderr: capBashOutput(patch.stderr) } : {}),
+        };
+    }
+}
+//# sourceMappingURL=bash-card-session.js.map

package/dist/card/bash-renderer.d.ts

@@ -0,0 +1,24 @@
+import type { RunCardRenderOptions } from './run-renderer.js';
+export interface BashRenderOptions extends RunCardRenderOptions {
+}
+/**
+ * Minimal card state for bash command output.
+ */
+export interface BashState {
+    runId: string;
+    terminal: 'running' | 'done' | 'error' | 'interrupted';
+    output: string;
+    stderr: string;
+    exitCode: number | null;
+    command: string;
+}
+/**
+ * Render a bash command output card (CardKit 2.0).
+ *
+ * 自带 stringify 级预算保护（与 renderRunCard 对称）：
+ * - 正常路径：output/stderr 各 ≤ OUTPUT_MAX_BYTES，组装后检查总卡字节
+ * - 超限 → degraded：output/stderr 各截到 DEGRADED_OUTPUT_BYTES 重新组装
+ * - 仍超限 → extreme：省略 output/stderr，保留 command + exitCode + 提示
+ * 所有返回路径保证 ≤ CARD_BUDGET_BYTES 且保留 command 与 exitCode（终态）。
+ */
+export declare function renderBashCard(state: BashState, _options?: BashRenderOptions): object;

package/dist/card/bash-renderer.js

@@ -0,0 +1,187 @@
+import { terminalToColor, terminalToLabel, stopButton } from './card-shared.js';
+import { markdownDiv } from './collapsible.js';
+import { truncateUtf8 } from './text-truncate.js';
+/**
+ * 飞书卡片大小限制（安全阈值，与 run-renderer 一致）。
+ * 本地定义，不从 card-budget.ts 导入（避免流式/静态耦合）。
+ */
+const CARD_BUDGET_BYTES = 28_000;
+/**
+ * 单个输出字段的默认最大字节数（保守值，用于正常路径）。
+ * 飞书卡片限制约 28KB，留余量给卡片其他部分（header、status row、footer）
+ * output + stderr 各自截断，组合后不超过限制（约 28KB - 2KB = 26KB）
+ * 每个字段上限 12KB 可确保组合不超限。
+ */
+const OUTPUT_MAX_BYTES = 12_000;
+/**
+ * Degraded 路径：output/stderr 各自更保守的上限。
+ * 高转义字符 JSON.stringify 膨胀约 1.8x，4KB 原始 → ~7.2KB JSON，
+ * 两字段合计 ~14.4KB，加 header/status/footer 余量充足。
+ */
+const DEGRADED_OUTPUT_BYTES = 4_000;
+/**
+ * Truncate long commands for display.
+ */
+function truncateCommand(cmd, maxLen = 40) {
+    if (cmd.length <= maxLen)
+        return cmd;
+    return cmd.slice(0, maxLen - 3) + '...';
+}
+/**
+ * Build the status row (status tag + command) element.
+ */
+function buildStatusRow(state) {
+    const { terminal, exitCode, command } = state;
+    const statusLabel = bashStatusTagLabel(terminal, exitCode);
+    return {
+        tag: 'column_set',
+        columns: [
+            {
+                tag: 'column',
+                width: 'auto',
+                elements: [{ tag: 'div', text: { content: statusLabel, tag: 'lark_md' } }],
+            },
+            {
+                tag: 'column',
+                width: 'grow',
+                elements: [
+                    { tag: 'div', text: { content: `⏱ ${truncateCommand(command, 40)}`, tag: 'lark_md' } },
+                ],
+            },
+        ],
+    };
+}
+/**
+ * Build the exit code footer elements (terminal states only).
+ */
+function buildExitFooter(state) {
+    if (state.terminal === 'running')
+        return [];
+    const statusText = state.exitCode !== null
+        ? `退出码: ${state.exitCode}`
+        : state.terminal === 'interrupted'
+            ? '已手动终止'
+            : '已完成';
+    return [{ tag: 'hr' }, markdownDiv(statusText)];
+}
+/**
+ * Assemble the card JSON from elements.
+ */
+function assembleCard(state, elements) {
+    return {
+        schema: '2.0',
+        config: { wide_screen_mode: true, update_multi: true },
+        header: {
+            template: bashHeaderTemplate2(state.terminal),
+            title: { content: bashHeaderTitle2(state.terminal), tag: 'plain_text' },
+        },
+        body: { elements },
+    };
+}
+/**
+ * Build elements for the normal path: full output/stderr (each ≤ OUTPUT_MAX_BYTES).
+ */
+function buildNormalElements(state) {
+    const { terminal, runId, output, stderr } = state;
+    const elements = [buildStatusRow(state)];
+    const truncatedOutput = output
+        ? truncateUtf8(output, OUTPUT_MAX_BYTES, true, '…（输出已截断，共 ' + output.length + ' 字符）')
+        : '';
+    const truncatedStderr = stderr
+        ? truncateUtf8(stderr, OUTPUT_MAX_BYTES, true, '…（诊断输出已截断，共 ' + stderr.length + ' 字符）')
+        : '';
+    if (truncatedOutput)
+        elements.push(markdownDiv(`\`\`\`\n${truncatedOutput}\n\`\`\``));
+    if (truncatedStderr)
+        elements.push(markdownDiv(`📋 诊断输出:\n\`\`\`\n${truncatedStderr}\n\`\`\``));
+    if (terminal === 'running') {
+        elements.push({ tag: 'div', text: { content: '‎', tag: 'lark_md' } }, stopButton(runId));
+    }
+    elements.push(...buildExitFooter(state));
+    return elements;
+}
+/**
+ * Build elements for the degraded path: output/stderr truncated to a smaller
+ * budget. Preserves command (status row) and exitCode (footer).
+ */
+function buildDegradedElements(state) {
+    const { terminal, runId, output, stderr } = state;
+    const elements = [buildStatusRow(state)];
+    const truncatedOutput = output
+        ? truncateUtf8(output, DEGRADED_OUTPUT_BYTES, true, '…（输出已截断，共 ' + output.length + ' 字符）')
+        : '';
+    const truncatedStderr = stderr
+        ? truncateUtf8(stderr, DEGRADED_OUTPUT_BYTES, true, '…（诊断输出已截断，共 ' + stderr.length + ' 字符）')
+        : '';
+    if (truncatedOutput)
+        elements.push(markdownDiv(`\`\`\`\n${truncatedOutput}\n\`\`\``));
+    if (truncatedStderr)
+        elements.push(markdownDiv(`📋 诊断输出:\n\`\`\`\n${truncatedStderr}\n\`\`\``));
+    if (terminal === 'running') {
+        elements.push({ tag: 'div', text: { content: '‎', tag: 'lark_md' } }, stopButton(runId));
+    }
+    elements.push(...buildExitFooter(state));
+    return elements;
+}
+/**
+ * Build elements for the extreme fallback: no output/stderr body, only
+ * status row (command) + exit footer + "output too large" hint.
+ * Guarantees a minimal card that still preserves command and exitCode.
+ */
+function buildExtremeFallbackElements(state) {
+    const { terminal, runId } = state;
+    const elements = [buildStatusRow(state)];
+    elements.push(markdownDiv('_⚠️ 输出过大已省略_'));
+    if (terminal === 'running') {
+        elements.push({ tag: 'div', text: { content: '‎', tag: 'lark_md' } }, stopButton(runId));
+    }
+    elements.push(...buildExitFooter(state));
+    return elements;
+}
+/**
+ * Render a bash command output card (CardKit 2.0).
+ *
+ * 自带 stringify 级预算保护（与 renderRunCard 对称）：
+ * - 正常路径：output/stderr 各 ≤ OUTPUT_MAX_BYTES，组装后检查总卡字节
+ * - 超限 → degraded：output/stderr 各截到 DEGRADED_OUTPUT_BYTES 重新组装
+ * - 仍超限 → extreme：省略 output/stderr，保留 command + exitCode + 提示
+ * 所有返回路径保证 ≤ CARD_BUDGET_BYTES 且保留 command 与 exitCode（终态）。
+ */
+export function renderBashCard(state, _options = {}) {
+    // Normal path
+    const card = assembleCard(state, buildNormalElements(state));
+    if (Buffer.byteLength(JSON.stringify(card), 'utf8') <= CARD_BUDGET_BYTES)
+        return card;
+    // Degraded: shrink output/stderr budgets
+    const degradedCard = assembleCard(state, buildDegradedElements(state));
+    if (Buffer.byteLength(JSON.stringify(degradedCard), 'utf8') <= CARD_BUDGET_BYTES) {
+        return degradedCard;
+    }
+    // Extreme fallback: drop output/stderr, keep command + exitCode + hint
+    return assembleCard(state, buildExtremeFallbackElements(state));
+}
+/** Bash status tag label */
+function bashStatusTagLabel(terminal, exitCode) {
+    if (terminal === 'running' || terminal === 'interrupted')
+        return terminalToLabel(terminal);
+    if (exitCode === 0)
+        return '成功';
+    if (exitCode !== null)
+        return '失败';
+    return '出错';
+}
+/** CardKit 2.0 header title */
+function bashHeaderTitle2(terminal) {
+    if (terminal === 'running')
+        return '💻 执行命令...';
+    if (terminal === 'error')
+        return '❌ 命令执行失败';
+    if (terminal === 'interrupted')
+        return '⏹ 已终止';
+    return '✅ 命令执行完成';
+}
+/** CardKit 2.0 header template */
+function bashHeaderTemplate2(terminal) {
+    return terminalToColor(terminal);
+}
+//# sourceMappingURL=bash-renderer.js.map

package/dist/card/card-budget.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 静态卡片体积保护
+ *
+ * 用于：auto-resume, /active, completion notification 等静态卡片
+ * 不适用于：run-renderer 的流式卡片（已有独立保护）
+ *
+ * Docs: https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukz/feishu-cards/card-components/containers/collapsible-panel
+ */
+interface CardBudgetOptions {
+    /** 最大事件面板数量（保留最新的） */
+    maxEventPanels?: number;
+    /** 单个面板内容最大字节数 */
+    maxPanelContentBytes?: number;
+    /** 截断提示文本 */
+    truncationHint?: string;
+}
+/**
+ * 静态卡片体积保护
+ *
+ * @param card - 原始卡片 JSON
+ * @param opts - 裁剪选项
+ * @returns 裁剪后的卡片 + 是否发生了裁剪 + 原因 + 截断前后字节数
+ */
+export declare function enforceCardBudget(card: object, opts?: CardBudgetOptions): {
+    card: object;
+    wasTruncated: boolean;
+    reason?: string;
+    bytesBefore: number;
+    bytesAfter: number;
+};
+export {};