lark-remote 0.5.6 → 0.5.7

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.7] - 2026-10-20
+
+### 新增
+
+- **DSH 运行的工具调用与运行状态进卡**：此前 DSH 直连的运行卡片只有正文、看不到任何工具调用。现在工具块以原生折叠面板呈现（与思考块同款交互，点标题展开、不经过服务端往返），运行中或失败的默认展开，正文按卡片内工具数量分配截断预算；摘要识别 DSH 的工具名与参数（`glob`、`web_search`、`todo_write`、`subagent`、`job_*`、`terminal_*` 等），标题显示不下时按**显示宽度**做中间省略——保住工具名与路径结尾，而不是从尾部切掉文件名。卡片还会投影 DSH 的 `session/control` 状态流（步数与上下文占用），并在首帧列出仍在后台运行的任务（终端里 `run_in_background` 起的进程活过了本轮），终态卡片可直接停止它们
+- **恢复卡片能看出思路**：DSH 的历史块分 `text` / `reasoning` / `tool-call` 三类，此前只认 `text`，于是一个真实会话里 371 段思考、12 段正文的恢复卡只剩一串工具调用。现在思考映射成 thinking、正文映射成回复，工具调用与结果合成同一个面板（标题带工具名与命令，失败标 `❌`，正文是输出）
+- **`/resume` 卡保住「我上一句 + 你最后一句」**：卡片只显示最后 N 个块，用户最关心的「我刚说了什么、它最后答了什么」常被中间的工具往返挤出窗口。现在这两句有独立名额
+
+### 修复
+
+- **手机端窄屏排版**：状态行原先用并排短列布局，窄屏上会被挤成竖排（「运行中」三个字竖着排），且列宽由客户端决定、服务端控制不了。改为单行单块 + ` · ` 分隔，并补上本轮耗时
+- **卡片元素总数上限按实测收敛**：飞书拒绝的判据是递归 `elements` 成员数量，此前记录有误。现在运行卡片同时受字节预算与元素预算约束，超限时从最旧的步骤开始省略，不再整卡发送失败
+- **DSH 的停止不再假报已停止**：回合跑在共享的 `dsh web` 宿主里，退出本地进程带不走它。停止现在分两步——prompt 还没被回合取走时从宿主收件箱撤回，已被取走才发取消并用 `session/list.running` 轮询确认；无法确认时明确告知「可能仍在后台运行」，而不是报一句已停止。取消确认落地前，下一条消息由门禁拦住，避免会话级取消打到新回合；每次提交的在途身份另存一份，下次启动对账：清掉残留的待执行 prompt，对仍开着的回合只提示不代杀
+- **排队与压缩的回合归属**：排队中的 prompt 此前可能在上一个回合结束时被收尾，现在绑定到自己的回合；`/compact` 执行前先探服务端是否还有在途回合；进程退出时取消尚未收尾的回合，不留无人订阅的孤儿回合
+- **空闲判定改用会话状态**：此前靠事件流静默推断，工具往返密集时容易误判。现在读 `session/list.running`，事件探测降为兜底
+- **回顾卡不再被系统注入内容灌满**：DSH 的 `user/message` 里混着 agent 指令、技能清单、运行期上下文、压缩检查点等注入项，此前照单全收，回顾卡上看不见用户真正说过的话。现在按类型过滤，系统通知单独标 `🔔`
+- **Windows 与 CI 稳定性**：退出路径的取消与凭据检查统一走平台判定；若干用例的凭据路径断言跟随 `path.join`，不再写死 POSIX 字面量
+
+### 变更
+
+- **英文文档补齐 DSH 部分**：`docs/en/architecture/design.md` 补上停止与取消确认的叙述，`docs/en/architecture/streaming-card.md` 更正工具折叠的口径（此前写的「连续工具超过阈值折叠」已被实现取代），两侧不再有互相矛盾的说法
+- **用户文档纠正过期说法**：`/order` 别名的命令形态与存储位置（英文侧仍写已移除的 `/order alias <name> <text>` 与 `aliases.json`，实际是 `alias add|rm <orderId|序号>`、随指令存在 `orders.json`）、`/ws save` 示例多带一个实际不生效的路径参数、贡献指南要求 `bun run test` 而入门文档教的是 `bun test`、README 里真机用例的缺失目录前缀
+- **注释与文档整理**：入站消息两篇架构文档改为描述当前实现，测试文件头不再点名已不存在的文件。无行为变化
+
 ## [0.5.6] - 2026-10-18
 
 ### 新增
@@ -20,7 +44,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### 变更
 
 - **英文文档补齐 DSH 部分**：`docs/en/architecture/design.md` 补上直连与凭据签发、审批与提问转写、压缩能力声明；`docs/en/usage.md` 补 `manageProcess` / `dshHome` / `dshCommand` / `startTimeoutMs` / `permissionPreset` 五项配置说明，并纠正一处过期说法——原先写着 `token` 可以在 `/config` 卡片里编辑，实际该字段早已移出卡片
-- **注释与发布条目里的内部评审轮次标注清理**。无行为变化
+- **注释与发布条目整理**。无行为变化
 
 ## [0.5.5] - 2026-10-18
 
@@ -68,7 +92,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 变更
 
-- **注释里的运维现场数据与仓库外引用清理**：一处测试注释记录的崩溃进程号、实例名与精确到秒的重启时间改为占位描述；若干注释不再指向仓库之外的维护规范文件名。无行为变化
+- **注释里的运维数据与仓库外引用改为占位描述**。无行为变化
 
 ## [0.5.2] - 2026-10-11
 
@@ -96,7 +120,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **消除两处宿主环境相关的测试假红**：宿主带上本机没有的 locale（macOS 常见的 `LC_ALL=C.UTF-8`）时，bash 每次启动都往 stderr 打 setlocale 警告，让输出断言随机变红，测试 setup 阶段现在剔掉该变量（保留 UTF-8 解析所需项）；JSON-RPC 退出计时用例的计时起点从进程启动改到收到 `initialize` 应答，慢速 Windows runner 上不再因启动耗时超过阈值而误红
 - **英文架构文档补齐**：`docs/en/architecture/design.md` 增补与中文侧对应的五个章节，英中两侧不再不对称
-- **注释与用例名清理**：延续上一版的清理，去掉剩余指向未发布文档的引用与评审编号，并修正清理过程中留下的残句。无行为变化
+- **注释与用例名整理**：让公开仓库里的引用都能落地。无行为变化
 
 ## [0.5.0] - 2026-10-07
 
@@ -114,7 +138,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 变更
 
-- **注释与测试命名清理**：去掉源码、测试注释与用例名中指向未发布内部文档的引用（评审条目号、场景号、轮次号、文件名前缀），让公开仓库里的引用都能落地。无行为变化
+- **注释与测试命名整理**：让公开仓库里的引用都能落地。无行为变化
 
 ## [0.4.5] - 2026-10-07
 
@@ -468,13 +492,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### 测试
 
 - 合并 stub 工厂、净化 fixtures、移除冗余测试
-- 新增 P1-15 configContainer 锚点测试（含 codex 负向断言）
+- 新增 configContainer 锚点测试（含 codex 负向断言）
 
 ## [0.1.2] - 2026-08-10
 
 ### 修复
 
-- claude / opencode / kimi 的 Agent 工厂改为从 `configContainer` 读取配置，避免使用过期闭包导致配置不生效（P1-15）
+- claude / opencode / kimi 的 Agent 工厂改为从 `configContainer` 读取配置，避免使用过期闭包导致配置不生效
 - codex / kimi 的 `readSessionContent` 增加 cwd 校验，防止越界读取会话
 - `listClaudeSessions` / `isClaudeSessionActive` 支持跨目录回退，处理会话迁移后的定位
 - 修复 `handleQueueInput` 竞态：替换任务在 await 之前注册

package/README.en.md

@@ -137,8 +137,8 @@ bun run lint          # eslint
 
 # Live Feishu API integration tests (skipped by default; need valid
 # credentials under ~/.lark-remote-test)
-FEISHU_LIVE_TEST=1 bun run test tests/feishu-card-form-error.test.ts
-FEISHU_LIVE_TEST=1 bun run test tests/feishu-reaction-emoji-live.test.ts
+FEISHU_LIVE_TEST=1 bun run test tests/feishu-live/feishu-card-form-error.test.ts
+FEISHU_LIVE_TEST=1 bun run test tests/feishu-live/feishu-reaction-emoji-live.test.ts
 ```
 
 ## Documentation

package/README.md

@@ -141,8 +141,8 @@ bun run typecheck     # tsc --noEmit
 bun run lint          # eslint
 
 # 真实飞书 API 集成测试（默认跳过，需要 ~/.lark-remote-test 下的有效凭据）
-FEISHU_LIVE_TEST=1 bun run test tests/feishu-card-form-error.test.ts
-FEISHU_LIVE_TEST=1 bun run test tests/feishu-reaction-emoji-live.test.ts
+FEISHU_LIVE_TEST=1 bun run test tests/feishu-live/feishu-card-form-error.test.ts
+FEISHU_LIVE_TEST=1 bun run test tests/feishu-live/feishu-reaction-emoji-live.test.ts
 ```
 
 ## 文档

package/dist/bridge/index.d.ts

@@ -4,7 +4,7 @@ import type { SessionReaderRegistry, SessionStore } from '../session/index.js';
 import type { AppConfig } from '../config/index.js';
 import { type RunCardChannel } from '../card/run-card-session.js';
 import type { RunTerminal } from '../card/run-state.js';
-import { type AgentKind } from '../runner/types.js';
+import { type AgentKind, type StopOutcome } from '../runner/types.js';
 import { QueueManager, type QueuedTask, type EnqueueOptions, type AgentBinding, type ExecutingInfo } from './queue-manager.js';
 import type { InboundMediaPayload } from '../connector/index.js';
 import type { MediaOutcome } from '../inbound/turn.js';
@@ -46,6 +46,13 @@ export interface CommandResult {
     markdown?: string;
     card?: object;
 }
+/** Detailed result of one interrupt, for callers that must not over-promise. */
+export interface InterruptOutcome {
+    stopped: boolean;
+    agentKind?: AgentKind;
+    /** Present for DSH: what the remote stop actually achieved. */
+    stop?: StopOutcome;
+}
 export interface ActiveRunSnapshot {
     runId: string;
     userId: string;
@@ -151,6 +158,16 @@ export declare class Bridge {
      * 与 session 是否还在、能否压缩无关（2026-10-08 线上缺陷）。
      */
     private compactableRuns;
+    /**
+     * 终态卡片的渲染快照（runId → state + options），供「详情」在 run 结束后
+     * 仍能二次渲染。
+     *
+     * run 结束时 activeRuns 被清空，而卡片上的「详情」按钮还活着；没有快照，
+     * 点终态卡上的「详情」只能得到一句「已失效」。只保留最近若干条：单条快照
+     * 受 MAX_BLOCKS 约束（几十 KB 以内），用户只会点刚收到的卡。
+     */
+    private runCardSnapshots;
+    private static readonly RUN_CARD_SNAPSHOT_MAX;
     /**
      * Active `!` bash runs, keyed by runId (NOT cwd). Bash runs bypass the serial
      * queue and may run in parallel with claude runs / other bash runs in the same
@@ -318,6 +335,20 @@ export declare class Bridge {
          * omitted, all workspaces are candidates (used by /stop, /t, and card stop button which don't know which cwd to target). */
         cwd?: string;
     }): Promise<boolean>;
+    /**
+     * Same as {@link interruptCurrentRun}, plus what the runner's stop actually
+     * achieved. DSH returns a {@link StopOutcome} (withdrawn / cancelled /
+     * unconfirmed); process runners and bash return none.
+     *
+     * Callers use `stop.status === 'unconfirmed'` to avoid promising "stopped" or
+     * "executing immediately" when a turn may still be running in the host.
+     */
+    interruptCurrentRunDetailed(input: {
+        userId: string;
+        chatId: string;
+        runId?: string;
+        cwd?: string;
+    }): Promise<InterruptOutcome>;
     /** Send a result message to the user (§7). Returns true on success, false on failure. */
     sendResult(result: CommandResult, ctx: CommandContext): Promise<boolean>;
     /**
@@ -345,6 +376,22 @@ export declare class Bridge {
      * card id from their set on `false`.
      */
     patchCard(messageId: string, card: object): Promise<boolean>;
+    /**
+     * 终态快照的写入点：finalize 时把当前 state + 渲染选项留一份。
+     *
+     * 不放在 finish() 里：bridge 才知道 hasRunCompact 等渲染选项，且 eviction
+     * 与 activeRuns 生命周期在同一个地方收口。
+     */
+    private rememberRunCardSnapshot;
+    /**
+     * 停止终态卡上的一个后台任务。
+     *
+     * 后台任务的生命周期跨 run（这就是它需要单独入口的原因），所以解析路径是
+     * 终态快照（runId → sessionId/cwd/agentKind）+ 该工作区的 runner 实例，
+     * 而不是 activeRuns。成功后同步摘掉 state 里的任务并就地重渲染，否则按钮
+     * 会留在卡片上而任务早已结束。
+     */
+    killBackgroundJob(runId: string, jobId: string, ctx: CommandContext): Promise<boolean>;
     /** Send a file to the user via Feishu. */
     sendFile(filePath: string, ctx: CommandContext): Promise<void>;
     /**

package/dist/bridge/index.js

@@ -150,6 +150,16 @@ export class Bridge {
      * 与 session 是否还在、能否压缩无关（2026-10-08 线上缺陷）。
      */
     compactableRuns = new Map();
+    /**
+     * 终态卡片的渲染快照（runId → state + options），供「详情」在 run 结束后
+     * 仍能二次渲染。
+     *
+     * run 结束时 activeRuns 被清空，而卡片上的「详情」按钮还活着；没有快照，
+     * 点终态卡上的「详情」只能得到一句「已失效」。只保留最近若干条：单条快照
+     * 受 MAX_BLOCKS 约束（几十 KB 以内），用户只会点刚收到的卡。
+     */
+    runCardSnapshots = new Map();
+    static RUN_CARD_SNAPSHOT_MAX = 8;
     /**
      * Active `!` bash runs, keyed by runId (NOT cwd). Bash runs bypass the serial
      * queue and may run in parallel with claude runs / other bash runs in the same
@@ -575,6 +585,17 @@ export class Bridge {
         return result;
     }
     async interruptCurrentRun(input) {
+        return (await this.interruptCurrentRunDetailed(input)).stopped;
+    }
+    /**
+     * Same as {@link interruptCurrentRun}, plus what the runner's stop actually
+     * achieved. DSH returns a {@link StopOutcome} (withdrawn / cancelled /
+     * unconfirmed); process runners and bash return none.
+     *
+     * Callers use `stop.status === 'unconfirmed'` to avoid promising "stopped" or
+     * "executing immediately" when a turn may still be running in the host.
+     */
+    async interruptCurrentRunDetailed(input) {
         // Find the active claude run matching this user/chat
         for (const [cwd, active] of this.activeRuns) {
             if (input.cwd !== undefined && cwd !== input.cwd)
@@ -595,13 +616,18 @@ export class Bridge {
                 // unconditional reset would then zero the successor's count and mark
                 // its slot interrupted, hiding it from queue cards.
                 const stoppedSlot = this.queueManager.getExecutingSlot(cwd);
-                await Promise.allSettled([
+                const [, stopResult] = await Promise.allSettled([
                     // 用户主动中断（/stop、stop 卡按钮、queue.immediate）显式打标
                     // interruptedReason，与审批超时自动取消（approval_timeout）、审批
                     // 卡取消（approval_cancelled）在终态数据上可区分（方案 A）。
                     active.session.finish('interrupted', { interruptedReason: 'user_stop' }),
                     runner.stop({ immediate: true }),
                 ]);
+                const stop = stopResult.status === 'fulfilled' &&
+                    stopResult.value !== null &&
+                    typeof stopResult.value === 'object'
+                    ? stopResult.value
+                    : undefined;
                 // The chain may have advanced while the stop was in flight: a new run
                 // (from a task that began during the stop window) may now occupy this
                 // cwd. Only delete the entry we actually stopped.
@@ -641,7 +667,7 @@ export class Bridge {
                     this.queueManager.resetExecutingCount(cwd, stoppedSlot);
                 }
                 getLogger().info(`[lark-remote] interrupt stop done runId=${active.runId}`);
-                return true;
+                return { stopped: true, agentKind: active.agentKind, ...(stop ? { stop } : {}) };
             }
         }
         // Then check active bash runs (! commands). These bypass the serial queue
@@ -658,11 +684,11 @@ export class Bridge {
                 await b.cardSession.finish('interrupted', { exitCode: -1 });
                 this.activeBashRuns.delete(runId);
                 getLogger().info(`[lark-remote] interrupt bash stop done runId=${runId}`);
-                return true;
+                return { stopped: true };
             }
         }
         getLogger().debug(`[lark-remote] interrupt miss userId=${input.userId}`);
-        return false;
+        return { stopped: false };
     }
     /** Send a result message to the user (§7). Returns true on success, false on failure. */
     async sendResult(result, ctx) {
@@ -756,6 +782,47 @@ export class Bridge {
             return false;
         }
     }
+    /**
+     * 终态快照的写入点：finalize 时把当前 state + 渲染选项留一份。
+     *
+     * 不放在 finish() 里：bridge 才知道 hasRunCompact 等渲染选项，且 eviction
+     * 与 activeRuns 生命周期在同一个地方收口。
+     */
+    rememberRunCardSnapshot(runId, state, options, cwd, agentKind) {
+        this.runCardSnapshots.set(runId, { state, options, cwd, agentKind });
+        while (this.runCardSnapshots.size > Bridge.RUN_CARD_SNAPSHOT_MAX) {
+            const oldest = this.runCardSnapshots.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.runCardSnapshots.delete(oldest);
+        }
+    }
+    /**
+     * 停止终态卡上的一个后台任务。
+     *
+     * 后台任务的生命周期跨 run（这就是它需要单独入口的原因），所以解析路径是
+     * 终态快照（runId → sessionId/cwd/agentKind）+ 该工作区的 runner 实例，
+     * 而不是 activeRuns。成功后同步摘掉 state 里的任务并就地重渲染，否则按钮
+     * 会留在卡片上而任务早已结束。
+     */
+    async killBackgroundJob(runId, jobId, ctx) {
+        const snapshot = this.runCardSnapshots.get(runId);
+        const sessionId = snapshot?.state.sessionId;
+        if (!snapshot || !sessionId)
+            return false;
+        const runner = this.getRunner(snapshot.cwd, snapshot.agentKind);
+        if (typeof runner.killJob !== 'function')
+            return false;
+        const killed = await runner.killJob(sessionId, jobId);
+        if (!killed)
+            return false;
+        snapshot.state = {
+            ...snapshot.state,
+            backgroundJobs: (snapshot.state.backgroundJobs ?? []).filter((job) => job.id !== jobId),
+        };
+        await this.updateCardInPlace(renderRunCard(snapshot.state, snapshot.options), ctx);
+        return true;
+    }
     /** Send a file to the user via Feishu. */
     async sendFile(filePath, ctx) {
         try {
@@ -1222,7 +1289,10 @@ export class Bridge {
                                     await r.respondApproval(requestId, response);
                                 }
                             },
-                            interruptTurn: () => runner.stop(),
+                            interruptTurn: async () => {
+                                // DSH may return a StopOutcome; the coordinator only awaits.
+                                await runner.stop();
+                            },
                             pushToCard: async (events) => {
                                 for (const ev of events)
                                     await cardSession.push(ev);
@@ -1409,17 +1479,19 @@ export class Bridge {
         try {
             getLogger().debug(`[lark-remote] finally settle runId=${runId} state.terminal=${cardSession.currentState.terminal}`);
             const settleResult = await cardSession.settle();
+            // 卡片收尾后仍要能点「详情」：把终态 state 与当时的渲染选项留一份。
+            // 与 fallback 卡共用同一份 options（能力门控一致，展开后按钮语义不变）。
+            const finalRenderOptions = {
+                agentKind: activeRun.agentKind,
+                // 与 createRunSession 的 renderOptions 一致：fallback 卡也要按
+                // runner 能力门控 Compact 按钮（缺省 undefined = 显示按钮，
+                // DSH 等无 runCompact 的 agent 会渲染出点了报错的死按钮）。
+                compactSupported: this.hasRunCompact(cwd, activeRun.agentKind),
+            };
+            this.rememberRunCardSnapshot(runId, cardSession.currentState, finalRenderOptions, cwd, activeRun.agentKind);
             let runCardSent = false;
             if (settleResult === 'unsent') {
-                const sent = await this.sendResult({
-                    card: renderRunCard(cardSession.currentState, {
-                        agentKind: activeRun.agentKind,
-                        // 与 createRunSession 的 renderOptions 一致：fallback 卡也要按
-                        // runner 能力门控 Compact 按钮（缺省 undefined = 显示按钮，
-                        // DSH 等无 runCompact 的 agent 会渲染出点了报错的死按钮）。
-                        compactSupported: this.hasRunCompact(cwd, activeRun.agentKind),
-                    }),
-                }, ctx);
+                const sent = await this.sendResult({ card: renderRunCard(cardSession.currentState, finalRenderOptions) }, ctx);
                 runCardSent = sent;
             }
             else {

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,77 @@
 import { truncateUtf8, dropOldestMarkdownTables, countMarkdownTables, FEISHU_MAX_TABLES, CARD_BUDGET_BYTES, } from './text-truncate.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 +86,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 +100,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.

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

@@ -1,4 +1,13 @@
 import type { RunState, ToolEntry } from './run-state.js';
+/**
+ * 带「详情」按钮的工具行数上限（从最新往回数）。
+ *
+ * 按钮行是节点大户：`column_set` + 2 个 `column` + 标题 div/text + button/text/
+ * behaviors/value ≈ 10 个 JSON 节点；纯标题行只有 2 个。24 行全带按钮 ≈ 240 节点，
+ * 直接撞飞书的元素总数上限（实测 203 通过 / 204 失败，见 card-budget.ts）。
+ * 最近 8 行保留按钮（用户最可能展开的就是刚跑完的），更早的行退化成一行标题。
+ */
+export declare const MAX_TOOL_ROWS_WITH_BUTTON = 8;
 export interface RunCardRenderOptions {
     /**
      * Agent kind for the run card header title (e.g. "Claude · 思考中").
@@ -39,6 +48,21 @@ 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 还有一次。
+ *
+ * 导出供窄屏守卫测试断言分段宽度（与 `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[];