lark-remote 0.5.6 → 0.5.8

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

@@ -6,6 +6,43 @@
  *
  * Docs: https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukz/feishu-cards/card-components/containers/collapsible-panel
  */
+/**
+ * 飞书单卡「元素」总量上限（实测）。
+ *
+ * 2026-10-19 用真实 API 在测试会话探测（`tests/feishu-live/feishu-card-element-total-limit.test.ts`
+ * 与 `feishu-workspace-card-limit` / `feishu-order-active-card-limit`）：
+ *
+ * | 形状 | 结果 | elements 计数 |
+ * | --- | --- | --- |
+ * | 顶层平铺 99 个 div | ✅ | 99 |
+ * | 顶层平铺 100 个 div | ❌ 11310 | 100 |
+ * | 单列 column_set 内嵌 98 个 div | ✅ | 99 |
+ * | 单列 column_set 内嵌 99 个 div | ❌ | 100 |
+ * | `/order` 旧结构 20 行 | ❌ | 103 |
+ * | `/ws` 旧结构 20 行 | ❌ | 101 |
+ * | `/ws` 分页 15 行（整卡 227 个 JSON 对象） | ✅ | 80 |
+ *
+ * 判据是**递归统计 `elements` 数组成员**（不含 `columns`）**≤ 99**：所有实测的
+ * 成功/失败点都被它分开，而"整卡 JSON 对象数"分不开（`/ws` 分页卡 227 个对象
+ * 能发出去，平铺 100 个 div 只有 205 个对象却失败）。
+ *
+ * 另一个独立维度：单个 `column_set` 的列数（实测 66 列通过、67 列失败）。本仓库
+ * 所有卡片的列数都在 3 以内，用不到这个上限，仅在此记录以免再次误判。
+ *
+ * **旧结论勘误**：仓库曾把 `230025` 记为「elements 过多」。本次探测中它一次都
+ * 没有出现；元素超限统一是 `230099 / ErrCode: 11310 element exceeds the limit`。
+ *
+ * `MAX_CARD_ELEMENTS` 取 90（相对实测 99 留 10% 余量），用于渲染前的保守裁剪。
+ */
+export declare const MAX_CARD_ELEMENTS = 90;
+/**
+ * 卡片递归的 `elements` 数组成员数（`columns` 不计数）——与飞书实测边界对齐。
+ *
+ * 注意与"JSON 对象总数"不同：`column_set` 的 `column` 对象不计入，button 的
+ * `behaviors`/`value` 也不计入。用它做预算才既不误伤能发出去的卡片，也不放过
+ * 真正超限的卡片。
+ */
+export declare function countCardElements(card: unknown): number;
 interface CardBudgetOptions {
     /** 最大事件面板数量（保留最新的） */
     maxEventPanels?: number;

package/dist/card/card-budget.js

@@ -1,4 +1,79 @@
-import { truncateUtf8, dropOldestMarkdownTables, countMarkdownTables, FEISHU_MAX_TABLES, CARD_BUDGET_BYTES, } from './text-truncate.js';
+import { dropOldestMarkdownTables, countMarkdownTables, FEISHU_MAX_TABLES, CARD_BUDGET_BYTES, } from './text-truncate.js';
+import { truncateUtf8 } from '../common/truncate.js';
+import { cardWithHeader } from './card-shared.js';
+/**
+ * 静态卡片体积保护
+ *
+ * 用于：auto-resume, /active, completion notification 等静态卡片
+ * 不适用于：run-renderer 的流式卡片（已有独立保护）
+ *
+ * Docs: https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukz/feishu-cards/card-components/containers/collapsible-panel
+ */
+/**
+ * 飞书单卡「元素」总量上限（实测）。
+ *
+ * 2026-10-19 用真实 API 在测试会话探测（`tests/feishu-live/feishu-card-element-total-limit.test.ts`
+ * 与 `feishu-workspace-card-limit` / `feishu-order-active-card-limit`）：
+ *
+ * | 形状 | 结果 | elements 计数 |
+ * | --- | --- | --- |
+ * | 顶层平铺 99 个 div | ✅ | 99 |
+ * | 顶层平铺 100 个 div | ❌ 11310 | 100 |
+ * | 单列 column_set 内嵌 98 个 div | ✅ | 99 |
+ * | 单列 column_set 内嵌 99 个 div | ❌ | 100 |
+ * | `/order` 旧结构 20 行 | ❌ | 103 |
+ * | `/ws` 旧结构 20 行 | ❌ | 101 |
+ * | `/ws` 分页 15 行（整卡 227 个 JSON 对象） | ✅ | 80 |
+ *
+ * 判据是**递归统计 `elements` 数组成员**（不含 `columns`）**≤ 99**：所有实测的
+ * 成功/失败点都被它分开，而"整卡 JSON 对象数"分不开（`/ws` 分页卡 227 个对象
+ * 能发出去，平铺 100 个 div 只有 205 个对象却失败）。
+ *
+ * 另一个独立维度：单个 `column_set` 的列数（实测 66 列通过、67 列失败）。本仓库
+ * 所有卡片的列数都在 3 以内，用不到这个上限，仅在此记录以免再次误判。
+ *
+ * **旧结论勘误**：仓库曾把 `230025` 记为「elements 过多」。本次探测中它一次都
+ * 没有出现；元素超限统一是 `230099 / ErrCode: 11310 element exceeds the limit`。
+ *
+ * `MAX_CARD_ELEMENTS` 取 90（相对实测 99 留 10% 余量），用于渲染前的保守裁剪。
+ */
+export const MAX_CARD_ELEMENTS = 90;
+/**
+ * 卡片递归的 `elements` 数组成员数（`columns` 不计数）——与飞书实测边界对齐。
+ *
+ * 注意与"JSON 对象总数"不同：`column_set` 的 `column` 对象不计入，button 的
+ * `behaviors`/`value` 也不计入。用它做预算才既不误伤能发出去的卡片，也不放过
+ * 真正超限的卡片。
+ */
+export function countCardElements(card) {
+    let total = 0;
+    const walk = (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                walk(item);
+            return;
+        }
+        if (!value || typeof value !== 'object')
+            return;
+        const rec = value;
+        if (Array.isArray(rec.elements)) {
+            total += rec.elements.length;
+            walk(rec.elements);
+        }
+        if (Array.isArray(rec.columns)) {
+            walk(rec.columns);
+        }
+        // 继续下潜其余字段（`body`、`header` 等）：卡片根对象本身没有 elements，
+        // 不遍历字段就永远数到 0（曾因此让整条元素预算静默失效）。
+        for (const [key, child] of Object.entries(value)) {
+            if (key === 'elements' || key === 'columns')
+                continue;
+            walk(child);
+        }
+    };
+    walk(card);
+    return total;
+}
 /**
  * 静态卡片体积保护
  *
@@ -13,11 +88,12 @@ export function enforceCardBudget(card, opts = {}) {
     const cardStr = JSON.stringify(card);
     const bytesBefore = Buffer.byteLength(cardStr, 'utf8');
     const parsed = JSON.parse(cardStr);
+    const elementsBefore = countCardElements(parsed);
     const droppedTables = capCardMarkdownTables(parsed, FEISHU_MAX_TABLES);
     if (droppedTables > 0) {
         const fixedStr = JSON.stringify(parsed);
-        // table 截断后可能仍超字节预算，继续走后续阶段
-        if (Buffer.byteLength(fixedStr, 'utf8') <= CARD_BUDGET_BYTES) {
+        // table 截断后可能仍超预算（字节或元素总数），继续走后续阶段
+        if (fitsBudget(Buffer.byteLength(fixedStr, 'utf8'), countCardElements(parsed))) {
             return {
                 card: parsed,
                 wasTruncated: true,
@@ -26,15 +102,64 @@ export function enforceCardBudget(card, opts = {}) {
                 bytesAfter: Buffer.byteLength(fixedStr, 'utf8'),
             };
         }
-        // table 修好了但字节仍超，用 fixed 作为后续处理的起点
-        return enforceByteBudget(parsed, opts, bytesBefore);
+        return enforceElementBudget(parsed, opts, bytesBefore);
     }
-    if (bytesBefore <= CARD_BUDGET_BYTES) {
+    if (fitsBudget(bytesBefore, elementsBefore)) {
         return { card, wasTruncated: false, bytesBefore, bytesAfter: bytesBefore };
     }
+    // 元素总数超限：table 与字节可能都正常，必须先按元素数裁剪。
+    if (bytesBefore <= CARD_BUDGET_BYTES && elementsBefore > MAX_CARD_ELEMENTS) {
+        return enforceElementBudget(parsed, opts, bytesBefore);
+    }
     // 字节超限但 table 不超限
     return enforceByteBudget(JSON.parse(cardStr), opts, bytesBefore);
 }
+/** 同时满足字节与元素总数两个预算。 */
+function fitsBudget(bytes, elements) {
+    return bytes <= CARD_BUDGET_BYTES && elements <= MAX_CARD_ELEMENTS;
+}
+/**
+ * 元素总数超限时的裁剪：先丢最老的面板，再交给字节路径继续降级。
+ *
+ * 与字节路径分开是因为成因正交：字节超限来自内容长度（截断内容即可），元素
+ * 超限来自元素个数（只能删元素）。两条路径共用 `getPanelIndices`。
+ */
+function enforceElementBudget(card, opts = {}, bytesBefore) {
+    const reasons = [];
+    const elements = card.body?.elements ?? [];
+    const size = () => Buffer.byteLength(JSON.stringify(card), 'utf8');
+    const done = (wasTruncated) => ({
+        card,
+        wasTruncated,
+        reason: reasons.join('+') || undefined,
+        bytesBefore: bytesBefore ?? size(),
+        bytesAfter: size(),
+    });
+    const dropPanels = (count) => {
+        const indices = getPanelIndices(elements)
+            .slice(0, count)
+            .sort((a, b) => b - a);
+        for (const idx of indices)
+            elements.splice(idx, 1);
+        return indices.length;
+    };
+    // 阶段1：面板按数量砍（面板是节点大户：一个面板外壳 + 内容）
+    const panelCount = getPanelIndices(elements).length;
+    if (panelCount > 0) {
+        let dropped = 0;
+        while (countCardElements(card) > MAX_CARD_ELEMENTS && getPanelIndices(elements).length > 0) {
+            dropped += dropPanels(1);
+        }
+        if (dropped > 0)
+            reasons.push('element_budget_panels_dropped');
+    }
+    if (countCardElements(card) <= MAX_CARD_ELEMENTS && size() <= CARD_BUDGET_BYTES) {
+        return done(true);
+    }
+    // 阶段2：仍超限（既不是面板、或字节同时超）→ 交给字节路径继续降级，
+    // 它最终会落到最小卡（节点数固定很小）。
+    return enforceByteBudget(card, opts, bytesBefore);
+}
 /**
  * Byte-budget enforcement, extracted so table-limit fix can delegate to it
  * when table truncation alone doesn't bring the card under the byte limit.
@@ -134,25 +259,19 @@ function enforceByteBudget(truncated, opts = {}, bytesBefore) {
         return done(true);
     }
     // ========== 阶段5：最终兜底（原 extreme_fallback） ==========
-    const minimalCard = {
-        schema: '2.0',
-        config: { wide_screen_mode: true },
-        header: {
-            template: 'orange',
-            title: { tag: 'plain_text', content: '⚠️ 内容已截断' },
-        },
-        body: {
-            elements: [
-                {
-                    tag: 'div',
-                    text: {
-                        tag: 'lark_md',
-                        content: '会话内容过大，已自动截断。\n\n请使用 `/active` 查看完整列表。',
-                    },
+    const minimalCard = cardWithHeader({
+        template: 'orange',
+        title: '⚠️ 内容已截断',
+        elements: [
+            {
+                tag: 'div',
+                text: {
+                    tag: 'lark_md',
+                    content: '会话内容过大，已自动截断。\n\n请使用 `/active` 查看完整列表。',
                 },
-            ],
-        },
-    };
+            },
+        ],
+    });
     return {
         card: minimalCard,
         wasTruncated: true,

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

@@ -107,19 +107,9 @@ export declare abstract class CardSession<S, RO = unknown> {
     start(): Promise<void>;
     settle(): Promise<StreamSettleResult>;
     /**
-     * Whether renderCard() already enforces a size budget (so updateCard can
-     * skip enforceCardBudget). Subclasses whose renderer has its own
-     * stringify-level budget protection (e.g. RunCardSession via degraded/
-     * extreme fallback) should override this to return true.
-     */
-    protected hasOwnBudgetProtection(): boolean;
-    /**
-     * Render the current card and apply stringify-level budget enforcement unless
-     * the subclass renderer has its own budget protection. Centralizes the budget
-     * decision so start()/updateCard()/settle() stay symmetric — previously only
-     * updateCard() guarded, while start() producer and settle() fallback sent bare
-     * renderCard output (risking >28KB for BashCardSession, which has no own
-     * stringify-level safety net).
+     * 渲染当前卡片。所有生产子类的 renderer 都自带 stringify 级预算保护
+     * （run/bash 的 degraded/extreme 路径）；发送前 Bridge 还会再走一次
+     * enforceCardBudget，因此这里不再重复裁剪。
      */
     protected safeRenderCard(): object;
     /**

package/dist/card/card-session.js

@@ -1,5 +1,4 @@
 import { getLogger } from '../logger/index.js';
-import { enforceCardBudget } from './card-budget.js';
 /**
  * Base class for single-card streaming sessions (RunCardSession, BashCardSession).
  * Provides the shared lifecycle: start → (push/update) → finish → settle.
@@ -216,25 +215,12 @@ export class CardSession {
         }
     }
     /**
-     * Whether renderCard() already enforces a size budget (so updateCard can
-     * skip enforceCardBudget). Subclasses whose renderer has its own
-     * stringify-level budget protection (e.g. RunCardSession via degraded/
-     * extreme fallback) should override this to return true.
-     */
-    hasOwnBudgetProtection() {
-        return false;
-    }
-    /**
-     * Render the current card and apply stringify-level budget enforcement unless
-     * the subclass renderer has its own budget protection. Centralizes the budget
-     * decision so start()/updateCard()/settle() stay symmetric — previously only
-     * updateCard() guarded, while start() producer and settle() fallback sent bare
-     * renderCard output (risking >28KB for BashCardSession, which has no own
-     * stringify-level safety net).
+     * 渲染当前卡片。所有生产子类的 renderer 都自带 stringify 级预算保护
+     * （run/bash 的 degraded/extreme 路径）；发送前 Bridge 还会再走一次
+     * enforceCardBudget，因此这里不再重复裁剪。
      */
     safeRenderCard() {
-        const card = this.renderCard(this.state, this.renderOptions);
-        return this.hasOwnBudgetProtection() ? card : enforceCardBudget(card).card;
+        return this.renderCard(this.state, this.renderOptions);
     }
     /**
      * Push an update to the card. Tries controller.update first, falls back to

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

@@ -9,6 +9,15 @@ import { type AgentKind } from '../runner/index.js';
 export declare function agentDisplayName(kind: string): string;
 export declare function terminalToLabel(terminal: string): string;
 export declare function terminalToColor(terminal: string): string;
+/**
+ * CardKit 2.0 静态卡骨架：schema/config/header + 给定 body elements。
+ * 队列状态卡、预算兜底卡等"只有 header 文案 + 少量 div"的卡共用。
+ */
+export declare function cardWithHeader(opts: {
+    template: string;
+    title: string;
+    elements: object[];
+}): object;
 /**
  * Create a CardKit 2.0 button with a callback behavior. Shared constructor
  * for every callback button in the card module (stop/new-session/compact/
@@ -21,6 +30,8 @@ export declare function cardButton(text: string, value: Record<string, unknown>,
     size?: 'small' | 'medium' | 'large';
     /** Fixed width, e.g. '100px' (keeps option-row buttons left-aligned). */
     width?: string;
+    /** 置灰（当前项 / 不可执行），仍保留回调 payload。 */
+    disabled?: boolean;
 }): object;
 /**
  * Create a CardKit 2.0 stop button with behaviors callback.

package/dist/card/card-shared.js

@@ -1,4 +1,5 @@
 import { AgentRegistry } from '../runner/index.js';
+import { AGENT_DISPLAY_NAMES } from '../runner/types.js';
 /**
  * Display name for an agent kind in the run card header.
  *
@@ -11,19 +12,8 @@ export function agentDisplayName(kind) {
     if (globalReg) {
         return globalReg.getDisplayName(kind);
     }
-    // Fallback: hardcoded default mapping for unit tests that exercise
-    // render helpers without booting the full AgentRegistry.
-    if (kind === 'claude')
-        return 'Claude';
-    if (kind === 'codex')
-        return 'Codex';
-    if (kind === 'opencode')
-        return 'Opencode';
-    if (kind === 'pi')
-        return 'Pi';
-    if (kind === 'kimi')
-        return 'Kimi';
-    return kind;
+    // Fallback for render helpers that run without the global registry.
+    return AGENT_DISPLAY_NAMES[kind] ?? kind;
 }
 const TERMINAL_LABELS = {
     done: '已完成',
@@ -51,6 +41,21 @@ export function terminalToColor(terminal) {
         return 'blue';
     return 'red';
 }
+/**
+ * CardKit 2.0 静态卡骨架：schema/config/header + 给定 body elements。
+ * 队列状态卡、预算兜底卡等"只有 header 文案 + 少量 div"的卡共用。
+ */
+export function cardWithHeader(opts) {
+    return {
+        schema: '2.0',
+        config: { wide_screen_mode: true },
+        header: {
+            template: opts.template,
+            title: { tag: 'plain_text', content: opts.title },
+        },
+        body: { elements: opts.elements },
+    };
+}
 /**
  * Create a CardKit 2.0 button with a callback behavior. Shared constructor
  * for every callback button in the card module (stop/new-session/compact/
@@ -65,6 +70,7 @@ export function cardButton(text, value, opts = {}) {
         ...(opts.type ? { type: opts.type } : {}),
         ...(opts.size ? { size: opts.size } : {}),
         ...(opts.width ? { width: opts.width } : {}),
+        ...(opts.disabled !== undefined ? { disabled: opts.disabled } : {}),
         behaviors: [{ type: 'callback', value }],
     };
 }

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

@@ -18,7 +18,6 @@ export declare class RunCardSession extends CardSession<RunState, RunCardRenderO
     protected get logPrefix(): string;
     protected get errorPrefix(): string;
     protected renderCard(state: RunState, options: RunCardRenderOptions): object;
-    protected hasOwnBudgetProtection(): boolean;
     protected isFlushableState(): boolean;
     push(event: AgentEvent): Promise<void>;
     finish(terminal: Exclude<RunTerminal, 'running' | 'finalizing'>, meta?: FinishMeta): Promise<void>;

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

@@ -22,12 +22,6 @@ export class RunCardSession extends CardSession {
     renderCard(state, options) {
         return renderRunCard(state, options);
     }
-    hasOwnBudgetProtection() {
-        // renderRunCard has 3-tier degraded/extreme fallback budget protection
-        // that guarantees the returned card is <= 28KB, so the base-class
-        // enforceCardBudget stringify pass is redundant for run cards.
-        return true;
-    }
     isFlushableState() {
         // finish() 已转终态（done/error/interrupted/idle_timeout）时不再 patch；
         // 'finalizing' 是非终态，in-flight/延迟 flush 仍可渲染累积事件。

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

@@ -39,6 +39,24 @@ type BlockGroup = {
 };
 /** 每个块的截断后内容（thinking/plan/text），测量与渲染共用（建议项）。 */
 type GroupContentPrepared = Map<BlockGroup, string>;
+/**
+ * 状态行内容：**一行、一个 div、窄屏不换行**。
+ *
+ * 设计约束（2026-10-19 手机端实测）：旧版把「状态标签」和「耗时/指标」放进
+ * `column_set` 的 auto + grow 两列，窄屏上 auto 列被挤到只剩两个字宽，
+ * "运行中" 被拆成 "运行 / 中"。列式布局的可用宽度取决于对端渲染，服务端无法
+ * 保证；所以这里改成单 div，段间用 " · " 分隔——换行只会发生在分隔符处，
+ * 而且整行控制在 ~26 个半角宽度内，320px 宽的手机也能放下。
+ *
+ * 状态标签（运行中/已完成…）不再重复：header 已经写了（`🔧 dsh · 调用工具`
+ * / `✅ dsh · 已完成`），终态 summary 还有一次。
+ *
+ * 终态也保留状态行：耗时定格，DSH 的步数/上下文投影展示最后一次快照
+ * （2026-10-21 用户要求）。summary 的最终 usage 与状态行并存。
+ *
+ * 导出供窄屏守卫测试断言分段宽度（与 `estimateCardBytes` 同一惯例）。
+ */
+export declare function statusLine(state: RunState): string;
 /** 导出供测试断言估算精度（估算 ≈ 实际渲染字节，见 tests/anchor/run-card/run-card.test.ts）。 */
 export declare function estimateCardBytes(state: RunState, options?: RunCardRenderOptions, shared?: {
     groups?: BlockGroup[];