lark-remote 0.1.6 → 0.1.7

package/dist/card/approval-render.js

@@ -8,6 +8,24 @@
 function mkNonce() {
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
+/** reason div（3 处共用）；反引号中和防 lark_md 解析错误（review P2-2）。 */
+function reasonDiv(approval) {
+    if (!approval.reason)
+        return null;
+    const neutralized = approval.reason.replace(/`/g, '·');
+    return {
+        tag: 'div',
+        text: { tag: 'lark_md', content: `💡 ${neutralized}` },
+    };
+}
+/**
+ * Append a possibly-null element to the array (convenience for optional divs).
+ * If the element is null, nothing is appended.
+ */
+function pushIf(arr, el) {
+    if (el !== null)
+        arr.push(el);
+}
 /**
  * Render the approval area for a run card.
  * Returns an array of CardKit 2.0 elements to append to the card body.
@@ -30,6 +48,9 @@ export function renderApprovalArea(approval, opts) {
     else if (approval.kind === 'permissions') {
         elements.push(...renderPermissionsApproval(approval, opts?.expired, opts?.runId));
     }
+    else if (approval.kind === 'question') {
+        elements.push(...renderQuestionApproval(approval, opts?.expired, opts?.runId));
+    }
     return elements;
 }
 /**
@@ -51,11 +72,18 @@ function renderDecisionButtons(approval, expired, runId) {
         accept: { label: '✅ 允许', type: 'primary' },
         acceptForSession: { label: '✅ 允许本次会话', type: 'primary' },
         acceptWithExecpolicyAmendment: { label: '🔒 允许并记住命令', type: 'primary' },
+        acceptAll: { label: '✅ 允许所有', type: 'primary' },
         decline: { label: '❌ 拒绝', type: 'danger' },
     };
     // Fixed presentation order; only offer decisions the protocol listed
-    // (accept/decline are always available).
-    const offered = ['accept', 'acceptForSession', 'acceptWithExecpolicyAmendment', 'decline'].filter((d) => d === 'accept' || d === 'decline' || approval.availableDecisions.includes(d));
+    // (accept/decline are always available; acceptAll is Claude 专属「允许所有」)。
+    const offered = [
+        'accept',
+        'acceptForSession',
+        'acceptWithExecpolicyAmendment',
+        'acceptAll',
+        'decline',
+    ].filter((d) => d === 'accept' || d === 'decline' || approval.availableDecisions.includes(d));
     // 决策按钮逐个作为 body 直接元素返回（CardKit body 纵向堆叠 = 上下排列）。
     // 不能用 column_set width:auto 横排：手机窄屏下多个按钮挤在一行，按钮文字
     // 被截断成省略号，用户无法辨认审批动作。
@@ -83,7 +111,12 @@ function renderDecisionButtons(approval, expired, runId) {
 function renderCommandApproval(approval, expired, runId) {
     const elements = [];
     // Command display
-    const cmdContent = approval.command ? `\`${approval.command.slice(0, 500)}\`` : '(no command)';
+    // review P2-2：命令里的反引号会提前终止 lark_md 行内代码 span，奇数次
+    // 反引号极易触发 11311 解析错误导致整卡失败（同 renderFileDiff 的中和策略）。
+    const neutralizedCommand = (approval.command ?? '').replace(/`/g, '·');
+    const cmdContent = neutralizedCommand
+        ? `\`${neutralizedCommand.slice(0, 500)}\``
+        : '(no command)';
     elements.push({
         tag: 'div',
         text: { tag: 'lark_md', content: `**⚡ 命令审批**\n${cmdContent}` },
@@ -94,23 +127,11 @@ function renderCommandApproval(approval, expired, runId) {
             text: { tag: 'lark_md', content: `📂 \`${approval.commandCwd}\`` },
         });
     }
-    if (approval.reason) {
-        elements.push({
-            tag: 'div',
-            text: { tag: 'lark_md', content: `💡 ${approval.reason}` },
-        });
-    }
+    pushIf(elements, reasonDiv(approval));
     // Action buttons — derived from the real protocol decision list (see
     // renderDecisionButtons): accept/decline always, acceptForSession and
     // acceptWithExecpolicyAmendment only when the server offers them.
     elements.push(...renderDecisionButtons(approval, expired, runId));
-    // Pending count
-    if (approval.pendingTotal > 1) {
-        elements.push({
-            tag: 'div',
-            text: { tag: 'lark_md', content: `📋 还有 ${approval.pendingTotal - 1} 个待审批请求` },
-        });
-    }
     return elements;
 }
 // =============================================================================
@@ -122,12 +143,7 @@ function renderFileApproval(approval, expired, runId) {
         tag: 'div',
         text: { tag: 'lark_md', content: '**📄 文件变更审批**' },
     });
-    if (approval.reason) {
-        elements.push({
-            tag: 'div',
-            text: { tag: 'lark_md', content: `💡 ${approval.reason}` },
-        });
-    }
+    pushIf(elements, reasonDiv(approval));
     // File changes list
     if (approval.fileChanges && approval.fileChanges.length > 0) {
         // 审批区 diff 总预算：估算函数不计审批区，多文件大 diff 可能顶爆 28KB 卡
@@ -164,12 +180,6 @@ function renderFileApproval(approval, expired, runId) {
     // Action buttons
     // Derived from the real protocol decision list (see renderDecisionButtons).
     elements.push(...renderDecisionButtons(approval, expired, runId));
-    if (approval.pendingTotal > 1) {
-        elements.push({
-            tag: 'div',
-            text: { tag: 'lark_md', content: `📋 还有 ${approval.pendingTotal - 1} 个待审批请求` },
-        });
-    }
     return elements;
 }
 /**
@@ -195,12 +205,7 @@ function renderPermissionsApproval(approval, expired, runId) {
         tag: 'div',
         text: { tag: 'lark_md', content: '**🔒 权限审批**' },
     });
-    if (approval.reason) {
-        elements.push({
-            tag: 'div',
-            text: { tag: 'lark_md', content: `💡 ${approval.reason}` },
-        });
-    }
+    pushIf(elements, reasonDiv(approval));
     // Permission items with toggle buttons
     if (approval.permissions?.items) {
         for (const item of approval.permissions.items) {
@@ -236,11 +241,122 @@ function renderPermissionsApproval(approval, expired, runId) {
     // Action buttons
     // Derived from the real protocol decision list (see renderDecisionButtons).
     elements.push(...renderDecisionButtons(approval, expired, runId));
-    if (approval.pendingTotal > 1) {
+    return elements;
+}
+// =============================================================================
+// AskUserQuestion Approval
+// =============================================================================
+/**
+ * 渲染 Claude AskUserQuestion 选项卡（审批区复用）。
+ *
+ * - 单选问题：点击选项即选中（协调器在全部问题答完后自动提交）。
+ * - 多选问题：点击切换勾选，勾选后出现「提交答案」按钮。
+ * - 已选状态经 approval_view_updated 回流（view.questions[].selected）。
+ */
+function renderQuestionApproval(approval, expired, runId) {
+    const elements = [];
+    elements.push({
+        tag: 'div',
+        text: { tag: 'lark_md', content: '**❓ 需要你回答**' },
+    });
+    if (expired) {
+        elements.push({
+            tag: 'div',
+            text: { tag: 'lark_md', content: '⏰ **审批已过期**' },
+        });
+        return elements;
+    }
+    const questions = approval.questions ?? [];
+    for (let i = 0; i < questions.length; i++) {
+        const q = questions[i];
+        const selected = q.selected ?? [];
+        const header = q.header || `问题 ${i + 1}`;
         elements.push({
             tag: 'div',
-            text: { tag: 'lark_md', content: `📋 还有 ${approval.pendingTotal - 1} 个待审批请求` },
+            text: {
+                tag: 'lark_md',
+                content: `**${header}**${q.multiSelect ? '（可多选）' : ''}\n${q.question}`,
+            },
         });
+        for (const option of q.options) {
+            const isSelected = selected.includes(option.label);
+            elements.push({
+                tag: 'div',
+                text: {
+                    tag: 'lark_md',
+                    content: `${isSelected ? '✅' : '⬜'} ${option.label}${option.description ? `\n_${option.description}_` : ''}`,
+                },
+            });
+            elements.push({
+                tag: 'button',
+                text: { tag: 'plain_text', content: isSelected ? '取消选择' : '选择' },
+                type: isSelected ? 'default' : 'primary',
+                size: 'small',
+                behaviors: [
+                    {
+                        type: 'callback',
+                        value: {
+                            cmd: 'approval.answer',
+                            requestId: approval.requestId,
+                            questionIndex: i,
+                            option: option.label,
+                            runId,
+                            nonce: mkNonce(),
+                        },
+                    },
+                ],
+            });
+        }
+        // 自定义答案（Other）的选中态展示：选项按钮无法表示自由文本，单独显示
+        // 已选文本，避免「点了没反应」的困惑（review P3）。
+        const customSelected = q.selected?.find((s) => !q.options.some((o) => o.label === s));
+        if (customSelected) {
+            elements.push({
+                tag: 'div',
+                text: { tag: 'lark_md', content: `✍️ 自定义答案：${customSelected}` },
+            });
+        }
+        // review P3-4：单选问题提供自定义答案（Other）输入——输入文本后点击
+        // 输入框右侧 ✓ 提交图标，input_value 经 connector raw 事件回传。
+        if (!q.multiSelect) {
+            elements.push({
+                tag: 'input',
+                name: `answer-custom-${approval.requestId}-${i}`,
+                placeholder: { tag: 'plain_text', content: '自定义答案（Other）…' },
+                behaviors: [
+                    {
+                        type: 'callback',
+                        value: {
+                            cmd: 'approval.answerCustom',
+                            requestId: approval.requestId,
+                            questionIndex: i,
+                            runId,
+                            nonce: mkNonce(),
+                        },
+                    },
+                ],
+            });
+        }
+        // 多选问题：有勾选才给提交按钮（单选在协调器内即时提交）。
+        if (q.multiSelect && selected.length > 0) {
+            elements.push({
+                tag: 'button',
+                text: { tag: 'plain_text', content: `✅ 提交答案（已选 ${selected.length} 项）` },
+                type: 'primary',
+                behaviors: [
+                    {
+                        type: 'callback',
+                        value: {
+                            cmd: 'approval.answerSubmit',
+                            requestId: approval.requestId,
+                            questionIndex: i,
+                            runId,
+                            nonce: mkNonce(),
+                        },
+                    },
+                ],
+            });
+        }
     }
     return elements;
 }

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

@@ -1,4 +1,4 @@
-import { CardSession, type CardChannel, type StreamSettleResult } from './card-session.js';
+import { CardSession, type CardChannel } from './card-session.js';
 import { type BashState, type BashRenderOptions } from './bash-renderer.js';
 /**
  * Store-time 输出上限（字符，P1-3 层①）。§P1-3 建议「store-time 截断，
@@ -23,18 +23,6 @@ export declare function capBashOutput(value: string): string;
  * 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;
@@ -51,6 +39,7 @@ export declare class BashCardSession extends CardSession<BashState, BashRenderOp
     protected get errorPrefix(): string;
     protected renderCard(state: BashState, options: BashRenderOptions): object;
     protected hasOwnBudgetProtection(): boolean;
+    protected isFlushableState(): 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. */
@@ -59,17 +48,6 @@ export declare class BashCardSession extends CardSession<BashState, BashRenderOp
         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 付代价。

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

@@ -1,5 +1,6 @@
 import { CardSession } from './card-session.js';
 import { renderBashCard } from './bash-renderer.js';
+import { keepTail } from '../common/truncate.js';
 /**
  * Store-time 输出上限（字符，P1-3 层①）。§P1-3 建议「store-time 截断，
  * 保留尾部，上限如 24~64KB」——取区间下界 24_000 字符（字符上限 ×4 字节最坏
@@ -8,10 +9,6 @@ import { renderBashCard } from './bash-renderer.js';
  * 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 字符。
@@ -29,18 +26,6 @@ export function capBashOutput(value) {
  * 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,
@@ -56,8 +41,8 @@ export class BashCardSession extends CardSession {
             renderOptions: opts.renderOptions,
             startTimeoutMs: opts.startTimeoutMs,
             settleTimeoutMs: opts.settleTimeoutMs,
+            coalesceMs: opts.coalesceMs,
         });
-        this.coalesceMs = opts.coalesceMs ?? 100;
     }
     get logPrefix() {
         return '[bash-card]';
@@ -76,6 +61,10 @@ export class BashCardSession extends CardSession {
         // 卡应跳过它，靠自身 renderer 保护。
         return true;
     }
+    isFlushableState() {
+        // finish() 已把 state 转终态后，in-flight/延迟 flush 不再用旧 state patch。
+        return this.state.terminal === 'running';
+    }
     /** Patch the card with updated bash state (e.g. new stdout/stderr). */
     async update(patch) {
         this.state = this.applyCap(patch);
@@ -102,62 +91,6 @@ export class BashCardSession extends CardSession {
         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 付代价。

package/dist/card/bash-renderer.js

@@ -1,11 +1,10 @@
 import { terminalToColor, terminalToLabel, stopButton } from './card-shared.js';
 import { markdownDiv } from './collapsible.js';
-import { truncateUtf8 } from './text-truncate.js';
+import { truncateUtf8, CARD_BUDGET_BYTES } from './text-truncate.js';
 /**
  * 飞书卡片大小限制（安全阈值，与 run-renderer 一致）。
- * 本地定义，不从 card-budget.ts 导入（避免流式/静态耦合）。
+ * 从共享的 text-truncate.ts 导入，避免三处各自定义后数值漂移。
  */
-const CARD_BUDGET_BYTES = 28_000;
 /**
  * 单个输出字段的默认最大字节数（保守值，用于正常路径）。
  * 飞书卡片限制约 28KB，留余量给卡片其他部分（header、status row、footer）

package/dist/card/card-budget.js

@@ -1,6 +1,4 @@
-import { truncateUtf8, truncateMarkdownTables, countMarkdownTables, FEISHU_MAX_TABLES, } from './text-truncate.js';
-// 飞书卡片大小限制（安全阈值，取 run-renderer 相同值）
-const CARD_BUDGET_BYTES = 28_000;
+import { truncateUtf8, truncateMarkdownTables, countMarkdownTables, FEISHU_MAX_TABLES, CARD_BUDGET_BYTES, } from './text-truncate.js';
 /**
  * 静态卡片体积保护
  *
@@ -17,7 +15,6 @@ export function enforceCardBudget(card, opts = {}) {
     const totalTables = countCardTables(JSON.parse(cardStr));
     if (totalTables > FEISHU_MAX_TABLES) {
         // 深拷贝后对每个 lark_md 文本做 truncateMarkdownTables
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const fixed = JSON.parse(cardStr);
         truncateCardMarkdownTables(fixed);
         const fixedStr = JSON.stringify(fixed);
@@ -38,7 +35,6 @@ export function enforceCardBudget(card, opts = {}) {
         return { card, wasTruncated: false, bytesBefore, bytesAfter: bytesBefore };
     }
     // 字节超限但 table 不超限
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     return enforceByteBudget(JSON.parse(cardStr), opts, bytesBefore);
 }
 /**
@@ -59,12 +55,9 @@ export function enforceCardBudget(card, opts = {}) {
  *   阶段4 截断剩余顶层 div 文本
  *   阶段5 最终兜底 minimal card（骨架本身已超限的病理场景）
  */
-function enforceByteBudget(
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-truncated, opts = {}, bytesBefore) {
+function enforceByteBudget(truncated, opts = {}, bytesBefore) {
     const { maxEventPanels = 5, maxPanelContentBytes = 2000, truncationHint = '📜 还有 {count} 个事件未显示', } = opts;
     const reasons = [];
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const elements = truncated.body?.elements ?? [];
     const size = () => Buffer.byteLength(JSON.stringify(truncated), 'utf8');
     const done = (wasTruncated) => ({
@@ -173,7 +166,6 @@ truncated, opts = {}, bytesBefore) {
 /**
  * 在卡片头部插入「N 个事件未显示」提示（仅在有面板被移除时）。
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 function insertOmittedHint(elements, omitted, truncationHint) {
     if (omitted <= 0)
         return;
@@ -185,7 +177,6 @@ function insertOmittedHint(elements, omitted, truncationHint) {
 /**
  * 获取所有 collapsible_panel 的索引（结构化判定，不看标题文本）。
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 function getPanelIndices(elements) {
     const indices = [];
     for (let i = 0; i < elements.length; i++) {
@@ -196,84 +187,47 @@ function getPanelIndices(elements) {
     return indices;
 }
 /**
- * Count all markdown tables across every lark_md text field in a card JSON.
- * Recursively walks elements, collapsible_panel.elements, column.elements, etc.
+ * 遍历卡片元素树（含 collapsible_panel.elements 与 column_set.columns[].elements）。
+ *
+ * count 与 truncate 两条路径共用同一遍历，避免两套递归漂移（G5 Duplication）。
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function countCardTables(card) {
-    let total = 0;
-    const elements = card?.body?.elements ?? [];
+function walkCardElements(elements, visit) {
     for (const el of elements) {
-        total += countElementTables(el);
+        visit(el);
+        if (Array.isArray(el.elements))
+            walkCardElements(el.elements, visit);
+        if (Array.isArray(el.columns)) {
+            for (const col of el.columns) {
+                if (Array.isArray(col.elements))
+                    walkCardElements(col.elements, visit);
+            }
+        }
     }
-    return total;
 }
 /**
- * Recursively count markdown tables in a single element and its children.
+ * Count all markdown tables across every lark_md text field in a card JSON.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function countElementTables(el) {
-    let count = 0;
-    // lark_md div text
-    if (el.text?.tag === 'lark_md' && typeof el.text.content === 'string') {
-        count += countMarkdownTables(el.text.content);
-    }
-    // collapsible_panel inner elements
-    if (Array.isArray(el.elements)) {
-        for (const child of el.elements) {
-            count += countElementTables(child);
-        }
-    }
-    // column_set → columns → elements
-    if (Array.isArray(el.columns)) {
-        for (const col of el.columns) {
-            if (Array.isArray(col.elements)) {
-                for (const child of col.elements) {
-                    count += countElementTables(child);
-                }
-            }
+function countCardTables(card) {
+    let total = 0;
+    walkCardElements(card?.body?.elements ?? [], (el) => {
+        if (el.text?.tag === 'lark_md' && typeof el.text.content === 'string') {
+            total += countMarkdownTables(el.text.content);
         }
-    }
-    return count;
+    });
+    return total;
 }
 /**
  * In-place truncate markdown tables in every lark_md text field of a card,
  * keeping at most FEISHU_MAX_TABLES per field.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 function truncateCardMarkdownTables(card) {
-    const elements = card?.body?.elements ?? [];
-    for (const el of elements) {
-        truncateElementTables(el);
-    }
-}
-/**
- * Recursively truncate markdown tables in a single element and its children.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function truncateElementTables(el) {
-    // lark_md div text
-    if (el.text?.tag === 'lark_md' && typeof el.text.content === 'string') {
-        const truncated = truncateMarkdownTables(el.text.content);
-        if (truncated !== el.text.content) {
-            el.text.content = truncated;
-        }
-    }
-    // collapsible_panel inner elements
-    if (Array.isArray(el.elements)) {
-        for (const child of el.elements) {
-            truncateElementTables(child);
-        }
-    }
-    // column_set → columns → elements
-    if (Array.isArray(el.columns)) {
-        for (const col of el.columns) {
-            if (Array.isArray(col.elements)) {
-                for (const child of col.elements) {
-                    truncateElementTables(child);
-                }
+    walkCardElements(card?.body?.elements ?? [], (el) => {
+        if (el.text?.tag === 'lark_md' && typeof el.text.content === 'string') {
+            const truncated = truncateMarkdownTables(el.text.content);
+            if (truncated !== el.text.content) {
+                el.text.content = truncated;
             }
         }
-    }
+    });
 }
 //# sourceMappingURL=card-budget.js.map

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

@@ -52,10 +52,58 @@ export declare abstract class CardSession<S, RO = unknown> {
         renderOptions?: RO;
         startTimeoutMs?: number;
         settleTimeoutMs?: number;
+        /** update/push 合批窗口，默认 100ms（0 = 禁用合批，每事件立即 flush）。 */
+        coalesceMs?: number;
     });
+    /**
+     * 调度一次延迟 flush。已有 pending 调度则复用（合批核心）；否则起一个
+     * coalesceMs 定时器。flushInFlight 期间不再起 timer（避免重入叠加），但置
+     * pendingReschedule 以便 in-flight flush 完成后重新调度——否则 in-flight 期间
+     * 到达的 push/update 会停留为 stale 中间帧（P2-1）。
+     */
+    protected scheduleFlush(): void;
+    /**
+     * 执行一次 render + updateCard。合批窗口到期或 finish 即时 flush 时调用。
+     * flushInFlight 防止 timer 回调与 finish 的即时 flush 重入。
+     *
+     * 终态守卫：若 finish() 已把 state 转为终态，跳过本次 patch——避免 in-flight flush
+     * 用 pre-terminal state 覆盖 finish 已发的终态卡。finish() 自身会 await 任何
+     * in-flight flush 保证顺序，此守卫是双保险。
+     */
+    protected flush(): Promise<void>;
+    /**
+     * Whether the current state still permits a flush (i.e. is not yet terminal).
+     * Subclasses define their terminal set. Run treats 'finalizing' as non-terminal.
+     */
+    protected abstract isFlushableState(): boolean;
+    /**
+     * 取消待 flush 的合批调度（finish/settle 前清理，避免延迟 update 与终态
+     * 渲染竞争）。返回是否有被取消的 pending 调度。同时清掉 pendingReschedule，
+     * 防止 in-flight flush 的 finally 在 finish await 之后又起 dangling timer
+     * （finish 自身会渲染含累积事件的终态卡，无需 follow-up）。
+     */
+    protected cancelPendingFlush(): boolean;
     get currentState(): S;
     /** The messageId of the streaming card, available after `start()` resolves. */
     get cardMessageId(): string | undefined;
+    /**
+     * P1-3 合批窗口（ms）。连续事件各触发一次全卡 render + patch 是流式 CPU 主要
+     * 来源；窗口内多个事件复用同一次延迟 flush。窗口大小可通过 constructor 覆盖
+     * （测试用小窗口/0 禁用）。run/bash 子类共用的 flush 骨架（scheduleFlush/flush/
+     * cancelPendingFlush/settle）下沉到基类。
+     */
+    protected readonly coalesceMs: number;
+    private flushTimer;
+    private flushInFlight; /** P2-1：in-flight flush 期间到达的 push/update 标记。scheduleFlush 在
+     *  flushInFlight 时早退不调度新 timer，但事件已 reduce 进 state；若无此标志，
+     *  in-flight flush 完成后该事件无 follow-up render，停留为 stale 中间帧。
+     *  finally 检查此标志后重新 scheduleFlush，保证 in-flight 期间累积的事件最终被渲染。 */
+    private pendingReschedule;
+    /** 当前 in-flight flush 的 promise（若 flush 正在 await updateCard）。
+     *  finish() 在终态 patch 前 await 它，保证 in-flight 的 pre-terminal patch 先落地、
+     *  terminal patch 后落地——否则两条 controller.update 并发无 FIFO，
+     *  pre-terminal 可能在 terminal 之后 resolve 留下"思考中"终帧（P2）。 */
+    protected flushP: Promise<void> | undefined;
     start(): Promise<void>;
     settle(): Promise<StreamSettleResult>;
     /**