lark-remote 0.5.19 → 0.5.21

package/dist/card/approval-render.js

@@ -66,13 +66,18 @@ function pushIf(arr, el) {
     if (el !== null)
         arr.push(el);
 }
+const APPROVAL_AREA_RENDERERS = new Map([
+    ['command', renderCommandApproval],
+    ['tool', renderToolApproval],
+    ['file', renderFileApproval],
+    ['permissions', renderPermissionsApproval],
+    ['question', renderQuestionApproval],
+]);
 /**
  * Render the approval area for a run card.
  * Returns an array of CardKit 2.0 elements to append to the card body.
  */
 export function renderApprovalArea(approval, opts) {
-    if (!approval)
-        return [];
     // 终态（done/error/interrupted/idle_timeout）下 run 已结束：coordinator 已
     // 释放，按钮点击无处响应，隐藏整个审批区避免"点了没反应"。
     if (isTerminalHidden(opts))
@@ -85,21 +90,10 @@ export function renderApprovalArea(approval, opts) {
             text: { tag: 'lark_md', content: `ℹ️ ${neutralized}` },
         });
     }
-    if (approval.kind === 'command') {
-        elements.push(...renderCommandApproval(approval, opts?.expired, opts?.runId));
-    }
-    else if (approval.kind === 'tool') {
-        elements.push(...renderToolApproval(approval, opts?.expired, opts?.runId));
-    }
-    else if (approval.kind === 'file') {
-        elements.push(...renderFileApproval(approval, opts?.expired, opts?.runId));
-    }
-    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));
-    }
+    // kind → 渲染器查表（Map 保持插入顺序，未知 kind 与原先无 else 分支一致：不追加）。
+    const render = APPROVAL_AREA_RENDERERS.get(approval.kind);
+    if (render)
+        elements.push(...render(approval, opts?.expired, opts?.runId));
     // 响应发送失败：明确告知原因 + 可重试，而不是静默停在可点状态。
     if (approval.deliveryError) {
         const neutralized = capApprovalText(approval.deliveryError);
@@ -123,8 +117,6 @@ export function renderApprovalArea(approval, opts) {
  * 结构性保证 ≤ 几个元素 + ≤ 1KB 文本，审批入口（红线）在任何降级档都活着。
  */
 export function renderApprovalAreaCompact(approval, opts) {
-    if (!approval)
-        return [];
     if (isTerminalHidden(opts))
         return [];
     const elements = [
@@ -433,9 +425,26 @@ function renderFileDiff(diff) {
 }
 /** Per-diff render cap (chars), see TOTAL_DIFF_CHARS for the approval-area cap. */
 const MAX_DIFF_CHARS = 1200;
-// =============================================================================
-// Permissions Approval
-// =============================================================================
+/** 单个权限条目：label div + toggle 按钮（模块级命名函数，供循环逐个调用）。 */
+function renderPermissionItem(item, requestId, runId) {
+    const icon = item.selected ? '✅' : '⬜';
+    // label 仅展示（payload 用 item.id），可安全截断。
+    const label = capApprovalText(item.label, APPROVAL_LABEL_BYTES);
+    return [
+        {
+            tag: 'div',
+            text: { tag: 'lark_md', content: `${icon} ${label}` },
+        },
+        cardButton(item.selected ? '取消授予' : '授予', {
+            cmd: 'approval.toggle',
+            requestId,
+            permId: item.id,
+            selected: !item.selected,
+            runId,
+            nonce: mkNonce(),
+        }, { type: item.selected ? 'default' : 'primary', size: 'small' }),
+    ];
+}
 function renderPermissionsApproval(approval, expired, runId) {
     const elements = [];
     elements.push({
@@ -449,21 +458,7 @@ function renderPermissionsApproval(approval, expired, runId) {
         const items = approval.permissions.items.slice(0, MAX_RENDERED_CHANGE_ITEMS);
         const omittedItems = approval.permissions.items.length - items.length;
         for (const item of items) {
-            const icon = item.selected ? '✅' : '⬜';
-            // label 仅展示（payload 用 item.id），可安全截断。
-            const label = capApprovalText(item.label, APPROVAL_LABEL_BYTES);
-            elements.push({
-                tag: 'div',
-                text: { tag: 'lark_md', content: `${icon} ${label}` },
-            });
-            elements.push(cardButton(item.selected ? '取消授予' : '授予', {
-                cmd: 'approval.toggle',
-                requestId: approval.requestId,
-                permId: item.id,
-                selected: !item.selected,
-                runId,
-                nonce: mkNonce(),
-            }, { type: item.selected ? 'default' : 'primary', size: 'small' }));
+            elements.push(...renderPermissionItem(item, approval.requestId, runId));
         }
         if (omittedItems > 0) {
             elements.push({
@@ -533,112 +528,128 @@ function renderQuestionApproval(approval, expired, runId) {
             break;
         }
         renderedQuestions++;
-        const q = questions[i];
-        const selected = q.selected ?? [];
-        const header = capApprovalText(q.header || `问题 ${i + 1}`, APPROVAL_LABEL_BYTES);
-        const freeText = (q.options?.length ?? 0) === 0;
+        elements.push(...renderQuestionBlock(approval, i, runId));
+    }
+    // 提问卡底部统一「跳过回答」：走现有 approval.respond + decision=decline
+    // （coordinator 对 question 允许 decline 作为安全兜底），runner 按协议映射
+    // 跳过语义（Claude deny / Codex 空 answers / Kimi action decline / Pi cancelled）。
+    if (!expired) {
+        elements.push(cardButton('⏭️ 跳过回答', {
+            cmd: 'approval.respond',
+            decision: 'decline',
+            requestId: approval.requestId,
+            runId,
+            nonce: mkNonce(),
+        }, { type: 'default' }));
+    }
+    return elements;
+}
+/**
+ * 渲染单题区块：题面 + 详情面板 + 选项行/输入框 + （多选）提交按钮。
+ * 从 renderQuestionApproval 的循环体抽出；循环保留题数/元素预算裁剪与
+ * 卡片装配。交互组件（按钮/输入框）继续直挂 body elements——本函数输出
+ * 必须始终被 expectNoV1ActionContainer 断言覆盖（200861 红线，见
+ * run-renderer.test.ts 的 question 系列）；nonce 仍由各交互元素生成时
+ * 各自调用一次 mkNonce()，不在块外缓存复用。
+ */
+function renderQuestionBlock(approval, qIndex, runId) {
+    const q = approval.questions?.[qIndex];
+    // 越界防御（正常调用由循环边界保证）；不虚构题面。
+    if (!q)
+        return [];
+    const elements = [];
+    const selected = q.selected ?? [];
+    const header = capApprovalText(q.header || `问题 ${qIndex + 1}`, APPROVAL_LABEL_BYTES);
+    const freeText = (q.options?.length ?? 0) === 0;
+    elements.push({
+        tag: 'div',
+        text: {
+            tag: 'lark_md',
+            content: `**${header}**${q.multiSelect ? '（可多选）' : ''}\n${capApprovalText(q.question)}`,
+        },
+    });
+    if (q.detail) {
+        // 题面外的补充正文（DSH plan-review 提问把计划全文放这里）：必须随题
+        // 渲染，否则用户是在「看不见计划」的情况下批准。与 ExitPlanMode 的
+        // 计划面板同口径：反引号中和 + 表格限数 + 字节预算折叠展示。
+        const neutralized = q.detail.replace(/`/g, '·');
+        const content = truncateUtf8(truncateMarkdownTables(neutralized), PLAN_PANEL_BYTES);
+        elements.push(collapsibleMarkdownPanel({
+            title: '📋 详情',
+            expanded: false,
+            border: 'blue',
+            content,
+        }));
+    }
+    if (freeText) {
+        // 自由文本题（Codex options:null / Pi extension input）：无选项行，
+        // 直接渲染题面 + 输入框，提交走 answerCustom（coordinator 不要求有选项）。
+        elements.push(renderAnswerInput(approval.requestId, qIndex, q.placeholder ?? '输入回答…', runId));
+        // 已答回显：input_value 不跨卡片更新保留，多题场景下用户提交后若还有
+        // 其他问题未答，卡片必须展示已答文本（与自定义答案选中态同模式）。
+        const answered = q.selected?.find((s) => s.length > 0);
+        if (answered) {
+            elements.push({
+                tag: 'div',
+                text: { tag: 'lark_md', content: `✍️ 已答：${capApprovalText(answered)}` },
+            });
+        }
+        return elements;
+    }
+    // 选项渲染上限（label 是回调 payload 不可截断，只能按条数折叠）。
+    const options = q.options ?? [];
+    for (const option of options.slice(0, MAX_RENDERED_OPTIONS)) {
+        const isSelected = selected.includes(option.label);
+        // 单选/多选图标区分：单选 ⚪/🔵（radio 隐喻），多选 ⬜/☑️（checkbox 隐喻）。
+        const icon = q.multiSelect ? (isSelected ? '☑️' : '⬜') : isSelected ? '🔵' : '⚪';
+        elements.push(renderOptionRow(approval.requestId, qIndex, option, isSelected, icon, runId));
+    }
+    if (options.length > MAX_RENDERED_OPTIONS) {
         elements.push({
             tag: 'div',
             text: {
                 tag: 'lark_md',
-                content: `**${header}**${q.multiSelect ? '（可多选）' : ''}\n${capApprovalText(q.question)}`,
+                content: `_…另有 ${options.length - MAX_RENDERED_OPTIONS} 个选项未展示（卡片元素预算）_`,
             },
         });
-        if (q.detail) {
-            // 题面外的补充正文（DSH plan-review 提问把计划全文放这里）：必须随题
-            // 渲染，否则用户是在「看不见计划」的情况下批准。与 ExitPlanMode 的
-            // 计划面板同口径：反引号中和 + 表格限数 + 字节预算折叠展示。
-            const neutralized = q.detail.replace(/`/g, '·');
-            const content = truncateUtf8(truncateMarkdownTables(neutralized), PLAN_PANEL_BYTES);
-            elements.push(collapsibleMarkdownPanel({
-                title: '📋 详情',
-                expanded: false,
-                border: 'blue',
-                content,
-            }));
-        }
-        if (freeText) {
-            // 自由文本题（Codex options:null / Pi extension input）：无选项行，
-            // 直接渲染题面 + 输入框，提交走 answerCustom（coordinator 不要求有选项）。
-            elements.push(renderAnswerInput(approval.requestId, i, q.placeholder ?? '输入回答…', runId));
-            // 已答回显：input_value 不跨卡片更新保留，多题场景下用户提交后若还有
-            // 其他问题未答，卡片必须展示已答文本（与自定义答案选中态同模式）。
-            const answered = q.selected?.find((s) => s.length > 0);
-            if (answered) {
-                elements.push({
-                    tag: 'div',
-                    text: { tag: 'lark_md', content: `✍️ 已答：${capApprovalText(answered)}` },
-                });
-            }
-            continue;
-        }
-        // 选项渲染上限（label 是回调 payload 不可截断，只能按条数折叠）。
-        const options = q.options ?? [];
-        for (const option of options.slice(0, MAX_RENDERED_OPTIONS)) {
-            const isSelected = selected.includes(option.label);
-            // 单选/多选图标区分：单选 ⚪/🔵（radio 隐喻），多选 ⬜/☑️（checkbox 隐喻）。
-            const icon = q.multiSelect ? (isSelected ? '☑️' : '⬜') : isSelected ? '🔵' : '⚪';
-            elements.push(renderOptionRow(approval.requestId, i, option, isSelected, icon, runId));
-        }
-        if (options.length > MAX_RENDERED_OPTIONS) {
-            elements.push({
-                tag: 'div',
-                text: {
-                    tag: 'lark_md',
-                    content: `_…另有 ${options.length - MAX_RENDERED_OPTIONS} 个选项未展示（卡片元素预算）_`,
-                },
-            });
-        }
-        // 自定义答案（Other）的选中态展示：选项按钮无法表示自由文本，单独显示
-        // 已选文本，避免「点了没反应」的困惑。
-        const customSelected = q.selected?.find((s) => !q.options.some((o) => o.label === s));
-        if (customSelected) {
+    }
+    // 自定义答案（Other）的选中态展示：选项按钮无法表示自由文本，单独显示
+    // 已选文本，避免「点了没反应」的困惑。
+    const customSelected = q.selected?.find((s) => !q.options.some((o) => o.label === s));
+    if (customSelected) {
+        elements.push({
+            tag: 'div',
+            text: { tag: 'lark_md', content: `✍️ 自定义答案：${capApprovalText(customSelected)}` },
+        });
+    }
+    // 单选问题提供自定义答案（Other）输入——输入文本后提交
+    // （移动端键盘回车/完成键，桌面端输入框右侧提交图标），input_value 经
+    // connector raw 事件回传。
+    // 显隐按 isOther !== false：Kimi form 会丢弃非声明选项值，翻译时置
+    // isOther=false 隐藏输入；Claude 未设置该字段默认显示（行为不变）。
+    if (!q.multiSelect && q.isOther !== false) {
+        elements.push(renderAnswerInput(approval.requestId, qIndex, '自定义答案（Other）…', runId, 'approval.answerCustom'));
+    }
+    // Codex user_note：选项之外的补充说明（allowNote 数据驱动门控）。
+    // 提交走 answerNote（coordinator 记录 note，随答案一起提交），已填回显。
+    if (q.allowNote === true) {
+        elements.push(renderAnswerInput(approval.requestId, qIndex, '补充说明（可选）…', runId, 'approval.answerNote'));
+        if (q.note) {
             elements.push({
                 tag: 'div',
-                text: { tag: 'lark_md', content: `✍️ 自定义答案：${capApprovalText(customSelected)}` },
+                text: { tag: 'lark_md', content: `📝 ${capApprovalText(q.note)}` },
             });
         }
-        // 单选问题提供自定义答案（Other）输入——输入文本后提交
-        // （移动端键盘回车/完成键，桌面端输入框右侧提交图标），input_value 经
-        // connector raw 事件回传。
-        // 显隐按 isOther !== false：Kimi form 会丢弃非声明选项值，翻译时置
-        // isOther=false 隐藏输入；Claude 未设置该字段默认显示（行为不变）。
-        if (!q.multiSelect && q.isOther !== false) {
-            elements.push(renderAnswerInput(approval.requestId, i, '自定义答案（Other）…', runId, 'approval.answerCustom'));
-        }
-        // Codex user_note：选项之外的补充说明（allowNote 数据驱动门控）。
-        // 提交走 answerNote（coordinator 记录 note，随答案一起提交），已填回显。
-        if (q.allowNote === true) {
-            elements.push(renderAnswerInput(approval.requestId, i, '补充说明（可选）…', runId, 'approval.answerNote'));
-            if (q.note) {
-                elements.push({
-                    tag: 'div',
-                    text: { tag: 'lark_md', content: `📝 ${capApprovalText(q.note)}` },
-                });
-            }
-        }
-        // 多选问题：有勾选才给提交按钮（单选在协调器内即时提交）。
-        if (q.multiSelect && selected.length > 0) {
-            elements.push(cardButton(`✅ 提交答案（已选 ${selected.length} 项）`, {
-                cmd: 'approval.answerSubmit',
-                requestId: approval.requestId,
-                questionIndex: i,
-                runId,
-                nonce: mkNonce(),
-            }, { type: 'primary' }));
-        }
     }
-    // 提问卡底部统一「跳过回答」：走现有 approval.respond + decision=decline
-    // （coordinator 对 question 允许 decline 作为安全兜底），runner 按协议映射
-    // 跳过语义（Claude deny / Codex 空 answers / Kimi action decline / Pi cancelled）。
-    if (!expired) {
-        elements.push(cardButton('⏭️ 跳过回答', {
-            cmd: 'approval.respond',
-            decision: 'decline',
+    // 多选问题：有勾选才给提交按钮（单选在协调器内即时提交）。
+    if (q.multiSelect && selected.length > 0) {
+        elements.push(cardButton(`✅ 提交答案（已选 ${selected.length} 项）`, {
+            cmd: 'approval.answerSubmit',
             requestId: approval.requestId,
+            questionIndex: qIndex,
             runId,
             nonce: mkNonce(),
-        }, { type: 'default' }));
+        }, { type: 'primary' }));
     }
     return elements;
 }
@@ -693,7 +704,7 @@ function renderOptionRow(requestId, questionIndex, option, isSelected, icon, run
 function renderAnswerInput(requestId, questionIndex, placeholder, runId, cmd = 'approval.answerCustom') {
     // name 必须含 cmd，保证同一题同时渲染多个输入框（如单选选项题的
     // Other 输入 + Note 输入）时元素 name 唯一——飞书对同卡内重复 name
-    // 报 ErrCode 11310 拒绝整卡（2026-08-19 线上：name(answer-custom-0-0) duplicate）。
+    // 报 ErrCode 11310 拒绝整卡。
     const kind = cmd === 'approval.answerNote' ? 'note' : 'custom';
     return {
         tag: 'input',

package/dist/card/card-budget.js

@@ -160,125 +160,130 @@ function enforceElementBudget(card, opts = {}, bytesBefore) {
     // 它最终会落到最小卡（节点数固定很小）。
     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.
- *
- * 裁剪判定是**结构化**的：所有 collapsible_panel 都是待裁剪对象，不看面板
- * 标题文本。历史教训（2026-08-08）：旧实现用
- * emoji 标题模式（🤖👤💭🔧🟢🔴）识别「会话事件面板」，但真实
- * sessionEventPanel 产出的标题是裸英文 type 名（emoji 在事件正文而非标题），
- * 导致裁剪阶段对真实 resume 卡零命中，任何 >28KB 的卡片无裁剪直通极端降级，
- * 整卡被替换成一句话。
- *
- * 渐进式降级（每级仍超限才进入下一级）：
- *   阶段1 逐面板截断内容（maxPanelContentBytes）
- *   阶段2 限制面板数量（删除最老，maxEventPanels）
- *   阶段3 丢弃全部面板，保留骨架（header/usage/按钮）+ 省略提示
- *   阶段4 截断剩余顶层 div 文本
- *   阶段5 最终兜底 minimal card（骨架本身已超限的病理场景）
- */
-function enforceByteBudget(truncated, opts = {}, bytesBefore) {
+function makeByteBudgetContext(truncated, opts, bytesBefore) {
     const { maxEventPanels = 5, maxPanelContentBytes = 2000, truncationHint = '📜 还有 {count} 个事件未显示', } = opts;
-    const reasons = [];
-    const elements = truncated.body?.elements ?? [];
-    const size = () => Buffer.byteLength(JSON.stringify(truncated), 'utf8');
-    const done = (wasTruncated) => ({
-        card: truncated,
+    return {
+        truncated,
+        elements: truncated.body?.elements ?? [],
+        reasons: [],
+        omitted: 0,
+        modifications: 0,
+        textTruncations: 0,
+        maxEventPanels,
+        maxPanelContentBytes,
+        truncationHint,
+        bytesBefore,
+    };
+}
+/** 原 size 闭包：当前卡片序列化字节数。 */
+function byteBudgetSize(ctx) {
+    return Buffer.byteLength(JSON.stringify(ctx.truncated), 'utf8');
+}
+/** 原 done 闭包：构造结果对象（reason 由各阶段累积）。 */
+function byteBudgetDone(ctx, wasTruncated) {
+    return {
+        card: ctx.truncated,
         wasTruncated,
-        reason: reasons.join('+') || undefined,
-        bytesBefore: bytesBefore ?? size(),
-        bytesAfter: size(),
-    });
-    // ========== 阶段1：裁剪所有面板的内容 ==========
-    let modifications = 0;
-    for (const el of elements) {
+        reason: ctx.reasons.join('+') || undefined,
+        bytesBefore: ctx.bytesBefore ?? byteBudgetSize(ctx),
+        bytesAfter: byteBudgetSize(ctx),
+    };
+}
+/** 原 elementsWithinBudgetWithHint 闭包（含 hint 预留位）。 */
+function byteBudgetElementsWithin(ctx) {
+    return countCardElements(ctx.truncated) + (ctx.omitted > 0 ? 1 : 0) <= MAX_CARD_ELEMENTS;
+}
+/** 原 `size() <= ... && elementsWithinBudgetWithHint()` 达标判定。 */
+function byteBudgetFits(ctx) {
+    return byteBudgetSize(ctx) <= CARD_BUDGET_BYTES && byteBudgetElementsWithin(ctx);
+}
+function comparePanelIndexDesc(a, b) {
+    return b - a;
+}
+/** 原 dropOldestPanels 闭包：按文档顺序删最旧的 count 个面板。 */
+function dropOldestPanels(ctx, count) {
+    const indices = getPanelIndices(ctx.elements).slice(0, count).sort(comparePanelIndexDesc);
+    for (const idx of indices) {
+        ctx.elements.splice(idx, 1);
+        ctx.omitted++;
+    }
+}
+/** 达标则插入 hint 并返回结果；未达标返回 undefined，交给下一阶段继续降级。 */
+function byteBudgetTryFinish(ctx, wasTruncated) {
+    if (!byteBudgetFits(ctx))
+        return undefined;
+    insertOmittedHint(ctx.elements, ctx.omitted, ctx.truncationHint);
+    return byteBudgetDone(ctx, wasTruncated);
+}
+// ========== 阶段1：裁剪所有面板的内容 ==========
+function truncatePanelContents(ctx) {
+    for (const el of ctx.elements) {
         if (el.tag !== 'collapsible_panel')
             continue;
         for (const inner of el.elements ?? []) {
             if (inner.tag === 'div' && inner.text?.content) {
                 const content = inner.text.content;
-                if (Buffer.byteLength(content, 'utf8') > maxPanelContentBytes) {
-                    inner.text.content = truncateUtf8(content, maxPanelContentBytes);
-                    modifications++;
+                if (Buffer.byteLength(content, 'utf8') > ctx.maxPanelContentBytes) {
+                    inner.text.content = truncateUtf8(content, ctx.maxPanelContentBytes);
+                    ctx.modifications++;
                 }
             }
         }
     }
-    if (modifications > 0) {
-        reasons.push('panel_content_truncated');
-    }
-    // ========== 阶段2：限制面板数量（删除最老） ==========
-    let omitted = 0;
-    const dropOldestPanels = (count) => {
-        const indices = getPanelIndices(elements)
-            .slice(0, count)
-            .sort((a, b) => b - a);
-        for (const idx of indices) {
-            elements.splice(idx, 1);
-            omitted++;
-        }
-    };
-    const panelCount = getPanelIndices(elements).length;
-    if (panelCount > maxEventPanels) {
-        dropOldestPanels(panelCount - maxEventPanels);
-        reasons.push('event_count_limited');
-    }
-    // 元素数预算必须与字节预算同查（含 hint 预留位）：字节路径的返回条件此前
-    // 只看字节——元素超限但卡内无 collapsible_panel 时（如 95 个小 div），
-    // 阶段1-4 全是空操作，超限卡原样直通（实测 wasTruncated:false、95 元素
-    // > 90 → 飞书 11310 整卡报废，正是文件头注释记载的 /ws、/order 故障形态）。
-    const elementsWithinBudgetWithHint = () => countCardElements(truncated) + (omitted > 0 ? 1 : 0) <= MAX_CARD_ELEMENTS;
-    if (size() <= CARD_BUDGET_BYTES && elementsWithinBudgetWithHint()) {
-        insertOmittedHint(elements, omitted, truncationHint);
-        return done(modifications > 0 || omitted > 0);
+    if (ctx.modifications > 0) {
+        ctx.reasons.push('panel_content_truncated');
     }
-    // ========== 阶段3：丢弃全部面板，保留卡片骨架 ==========
-    // header（cwd/sessionId/标题）、usage、操作按钮等信息量高、体积小的元素
-    // 必须保留——整卡替换为一句话是信息损失最大的降级方式。
-    dropOldestPanels(getPanelIndices(elements).length);
-    if (omitted > 0) {
-        reasons.push('panels_dropped');
+}
+// ========== 阶段2：限制面板数量（删除最老） ==========
+function limitPanelCount(ctx) {
+    const panelCount = getPanelIndices(ctx.elements).length;
+    if (panelCount > ctx.maxEventPanels) {
+        dropOldestPanels(ctx, panelCount - ctx.maxEventPanels);
+        ctx.reasons.push('event_count_limited');
     }
-    if (size() <= CARD_BUDGET_BYTES && elementsWithinBudgetWithHint()) {
-        insertOmittedHint(elements, omitted, truncationHint);
-        return done(true);
+}
+// ========== 阶段3：丢弃全部面板，保留卡片骨架 ==========
+// header（cwd/sessionId/标题）、usage、操作按钮等信息量高、体积小的元素
+// 必须保留——整卡替换为一句话是信息损失最大的降级方式。
+function dropAllPanels(ctx) {
+    dropOldestPanels(ctx, getPanelIndices(ctx.elements).length);
+    if (ctx.omitted > 0) {
+        ctx.reasons.push('panels_dropped');
     }
-    // ========== 阶段4：截断剩余顶层 div 文本 ==========
-    // 骨架元素（header/usage 等）自身超限的情况（如超大 displayTitle）。
-    let textTruncations = 0;
-    for (const el of elements) {
+}
+// ========== 阶段4：截断剩余顶层 div 文本 ==========
+// 骨架元素（header/usage 等）自身超限的情况（如超大 displayTitle）。
+function truncateTopLevelDivs(ctx) {
+    for (const el of ctx.elements) {
         if (el.tag === 'div' && el.text?.content) {
             const content = el.text.content;
-            if (Buffer.byteLength(content, 'utf8') > maxPanelContentBytes) {
-                el.text.content = truncateUtf8(content, maxPanelContentBytes);
-                textTruncations++;
+            if (Buffer.byteLength(content, 'utf8') > ctx.maxPanelContentBytes) {
+                el.text.content = truncateUtf8(content, ctx.maxPanelContentBytes);
+                ctx.textTruncations++;
             }
         }
     }
-    if (textTruncations > 0) {
-        reasons.push('text_truncated');
+    if (ctx.textTruncations > 0) {
+        ctx.reasons.push('text_truncated');
     }
-    if (size() <= CARD_BUDGET_BYTES && elementsWithinBudgetWithHint()) {
-        insertOmittedHint(elements, omitted, truncationHint);
-        return done(true);
-    }
-    // ========== 阶段4.5：元素数兜底（无面板可删的元素超限） ==========
-    // 阶段1-4 只会裁内容/删面板；元素超限且无面板时在此按序丢弃最旧的顶层
-    // 元素直到达标（与 table/panel 的「删最旧、留最新」口径一致，尾部操作
-    // 按钮保留）。留 ≥3 个元素兜底，仍不达标则交给阶段5 的最小卡。
-    if (countCardElements(truncated) > MAX_CARD_ELEMENTS) {
-        while (countCardElements(truncated) > MAX_CARD_ELEMENTS && elements.length > 3) {
-            elements.shift();
-            omitted++;
-        }
-        reasons.push('element_budget_elements_dropped');
-        if (size() <= CARD_BUDGET_BYTES && elementsWithinBudgetWithHint()) {
-            insertOmittedHint(elements, omitted, truncationHint);
-            return done(true);
+}
+// ========== 阶段4.5：元素数兜底（无面板可删的元素超限） ==========
+// 阶段1-4 只会裁内容/删面板；元素超限且无面板时在此按序丢弃最旧的顶层
+// 元素直到达标（与 table/panel 的「删最旧、留最新」口径一致，尾部操作
+// 按钮保留）。留 ≥3 个元素兜底，仍不达标则交给阶段5 的最小卡。
+function dropExcessElements(ctx) {
+    if (countCardElements(ctx.truncated) > MAX_CARD_ELEMENTS) {
+        while (countCardElements(ctx.truncated) > MAX_CARD_ELEMENTS && ctx.elements.length > 3) {
+            ctx.elements.shift();
+            ctx.omitted++;
         }
+        ctx.reasons.push('element_budget_elements_dropped');
+        return byteBudgetTryFinish(ctx, true);
     }
-    // ========== 阶段5：最终兜底（原 extreme_fallback） ==========
+    return undefined;
+}
+// ========== 阶段5：最终兜底（原 extreme_fallback） ==========
+function byteBudgetMinimalCard(ctx) {
     const minimalCard = cardWithHeader({
         template: 'orange',
         title: '⚠️ 内容已截断',
@@ -296,10 +301,30 @@ function enforceByteBudget(truncated, opts = {}, bytesBefore) {
         card: minimalCard,
         wasTruncated: true,
         reason: 'extreme_fallback',
-        bytesBefore: bytesBefore ?? size(),
+        bytesBefore: ctx.bytesBefore ?? byteBudgetSize(ctx),
         bytesAfter: Buffer.byteLength(JSON.stringify(minimalCard), 'utf8'),
     };
 }
+function enforceByteBudget(truncated, opts = {}, bytesBefore) {
+    const ctx = makeByteBudgetContext(truncated, opts, bytesBefore);
+    truncatePanelContents(ctx);
+    limitPanelCount(ctx);
+    let result = byteBudgetTryFinish(ctx, ctx.modifications > 0 || ctx.omitted > 0);
+    if (result)
+        return result;
+    dropAllPanels(ctx);
+    result = byteBudgetTryFinish(ctx, true);
+    if (result)
+        return result;
+    truncateTopLevelDivs(ctx);
+    result = byteBudgetTryFinish(ctx, true);
+    if (result)
+        return result;
+    result = dropExcessElements(ctx);
+    if (result)
+        return result;
+    return byteBudgetMinimalCard(ctx);
+}
 /**
  * 在卡片头部插入「N 个事件未显示」提示（仅在有面板被移除时）。
  */

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

@@ -27,7 +27,7 @@ export declare function parseJumpOffset(inputValue: unknown, pageSize: number):
  * Build the CardKit 2.0 pagination block shared by /ls, /ws, /resume, /active,
  * /order.
  *
- * 第一性原理（2026-09-10 窄屏重设计）：分页栏要同时承载「页码信息」和「翻页
+ * 第一性原理（窄屏）：分页栏要同时承载「页码信息」和「翻页
  * 控件」两类需求。旧布局把两者塞进同一行 `column_set`（文案 weighted 4 : 输入
  * weighted 2），手机窄屏下 auto 按钮先占走固有宽度，剩余宽度按 4:2 切分后文案
  * 列只有百来像素、输入框只有几十像素——文案折行、输入框窄到没法点。
@@ -104,8 +104,8 @@ export declare function searchBar(opts: {
  *
  * 旧口径是 `events.slice(-max)`：按**原始事件条数**截尾。工具往返（bash 调用 →
  * job 登记 → 结果）一段就能把窗口占满，于是重返会话的用户真正需要的两条信息
- * ——最后一句我说了什么、最后一句它答了什么——被挤出窗口。2026-10-19 实测：
- * 自动恢复卡 5 个面板全是 bash 调用，一条用户消息、一条 assistant 正文都没有。
+ * ——最后一句我说了什么、最后一句它答了什么——被挤出窗口：自动恢复卡 5 个
+ * 面板全是 bash 调用，一条用户消息、一条 assistant 正文都没有。
  *
  * 契约：先取最新 `max` 条，再把最后一条 `user` 与最后一条 `assistant`（正文）
  * 不在窗口内时补进来——补位时淘汰最早的**非锚点**事件。输出保持时间顺序，