lark-remote 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.4.2] - 2026-09-19
+
+### 新增
+
+- **`/ws` `/ls` 列表卡关键词搜索**：两张列表卡各多出一行搜索输入框，输入关键词后**按回车提交**即可筛选。`/ws` 匹配别名或完整路径，`/ls` 只匹配**当前层**条目名（不递归子目录），均大小写不敏感、子串包含；计数与页码一律按过滤后的结果计算。筛选词不落服务端（只随卡片回调 payload 传递，且仅非空时注入），服务端保持零状态，未筛选时的卡片形态与旧版完全一致。筛选态下翻页/刷新/排序/使用/删除会保留关键词，进入其他目录或切换工作目录则清除筛选（换目录后旧关键词没有意义）
+
+### 修复
+
+- **卡片提交指引不再写「点 ✓」**：飞书移动端的 `input` 组件没有提交图标，只有键盘的回车/完成键（真机反馈）。所有用户可见文案统一为「按回车提交」，包括分页页码跳转、别名编辑、指令文本编辑与审批卡的修改意见
+- **取消筛选改走显式按钮**：「清空输入再回车」在部分客户端不会触发回调（官方文档未承诺空串会发回调），实测清空后回车没有反应。现在筛选态下搜索行右侧会出现**「清除筛选」**按钮，走显式标记强制清除，不再依赖「读不到输入值」这一隐式条件
+- **别名编辑卡不再把「留空提交」当删除入口**：同一处隐式条件问题，删除别名统一走列表卡别名旁的 ✕
+
+### 变更
+
+- 卡片布局文档（中英）补齐 CardKit `input` 的三条约束：没有逐键回调所以「边输边过滤」做不到、文案不写「点 ✓」、取消语义要有显式控件；`design.md` 中「input 提交图标」的表述改为「input 提交回传」（图标只是桌面端的一种触发方式）
+- 英文文档补齐 `/ws` `/ls` 关键词搜索：`README.en.md` 与 `docs/en/usage.md` 的命令表和功能段跟上中文口径
+
 ## [0.4.1] - 2026-09-18
 
 ### 新增

package/README.en.md

@@ -108,9 +108,9 @@ Your original message also gets an emoji reaction: `Typing` while the run is in
 |---------|-------|----------|
 | `/help` | `/h` | Command list |
 | `/cd <path>` | - | Switch agent working directory (`~`, absolute/relative; clears the session) |
-| `/ls [dir\|file]` | - | Directory/file card; click a directory to browse, click a file ≤30MB to send it to Feishu; paginates beyond 30 entries with a page-number jump input. Passing a file path lists that file itself |
+| `/ls [dir\|file]` | - | Directory/file card; click a directory to browse, click a file ≤30MB to send it to Feishu; paginates beyond 30 entries with a page-number jump input, and current-level entries can be filtered by keyword. Passing a file path lists that file itself |
 | `/download <path>` | `/d` | Send a local file straight to the chat (`~`, absolute/relative paths, 30MB cap) |
-| `/ws save\|use\|remove` | - | Named directory aliases (`/ws` lists by default) |
+| `/ws save\|use\|remove` | - | Named directory aliases (`/ws` lists by default, filterable by alias name or path keyword) |
 | `/resume [agent] [N\|id]` | `/r` | List/switch agent sessions for the current directory (card) |
 | `/active` | - | List all running sessions |
 | `/new` | - | Clear the current session (keeps cwd) |

package/README.md

@@ -108,9 +108,9 @@ lark-remote 启动后不在终端输出，运行日志写入 `~/.lark-remote/log
 |------|------|------|
 | `/help` | `/h` | 命令列表 |
 | `/cd <path>` | - | 切换 agent 工作目录（支持 `~`、绝对/相对路径，清空会话） |
-| `/ls [dir\|file]` | - | 弹出目录/文件卡片；点击目录切换，点击 30MB 内文件发送到飞书；条目 >30 时支持翻页与直接输入页码跳转。传文件路径时直接列出该文件（可下载） |
+| `/ls [dir\|file]` | - | 弹出目录/文件卡片；点击目录切换，点击 30MB 内文件发送到飞书；条目 >30 时支持翻页与直接输入页码跳转，卡片内可按关键词筛选本层条目。传文件路径时直接列出该文件（可下载） |
 | `/download <path>` | `/d` | 直接下载（发送）指定文件到飞书（支持 `~`、绝对/相对路径，上限 30MB） |
-| `/ws save\|use\|remove` | - | 命名目录别名管理（`/ws` 默认列出） |
+| `/ws save\|use\|remove` | - | 命名目录别名管理（`/ws` 默认列出，可按名称/路径关键词筛选） |
 | `/resume [agent] [N\|id]` | `/r` | 列出/切换当前目录的 agent session（卡片） |
 | `/active` | - | 列出所有正在进行中的 session |
 | `/new` | - | 清空当前会话（保留工作目录） |

package/dist/card/approval-render.js

@@ -207,9 +207,9 @@ function renderPlanApproval(approval, expired, runId) {
     return elements;
 }
 /**
- * 计划修改意见输入行：输入后点击右侧 ✓ 提交图标，input_value 经 connector
- * raw 事件回传（CardKit input 的 input_value 会被 SDK normalizer 丢弃，
- * 必须走 includeRawEvent 路径，同 answerNote）。
+ * 计划修改意见输入行：输入后提交（移动端键盘回车/完成键，桌面端右侧提交图标），
+ * input_value 经 connector raw 事件回传（CardKit input 的 input_value 会被
+ * SDK normalizer 丢弃，必须走 includeRawEvent 路径，同 answerNote）。
  */
 function renderPlanFeedbackInput(requestId, runId) {
     return {
@@ -430,8 +430,9 @@ function renderQuestionApproval(approval, expired, runId) {
                 text: { tag: 'lark_md', content: `✍️ 自定义答案：${customSelected}` },
             });
         }
-        // review P3-4：单选问题提供自定义答案（Other）输入——输入文本后点击
-        // 输入框右侧 ✓ 提交图标，input_value 经 connector raw 事件回传。
+        // review P3-4：单选问题提供自定义答案（Other）输入——输入文本后提交
+        // （移动端键盘回车/完成键，桌面端输入框右侧提交图标），input_value 经
+        // connector raw 事件回传。
         // 显隐按 isOther !== false：Kimi form 会丢弃非声明选项值，翻译时置
         // isOther=false 隐藏输入；Claude 未设置该字段默认显示（行为不变）。
         if (!q.multiSelect && q.isOther !== false) {
@@ -517,9 +518,9 @@ function renderOptionRow(requestId, questionIndex, option, isSelected, icon, run
     };
 }
 /**
- * 文本输入行（Other 输入与自由文本题共用）：输入后点击右侧 ✓ 提交图标，
- * input_value 经 connector raw 事件回传（CardKit input 的 input_value 会被
- * SDK normalizer 丢弃，必须走 includeRawEvent 路径）。
+ * 文本输入行（Other 输入与自由文本题共用）：输入后提交（移动端键盘回车/完成键，
+ * 桌面端右侧提交图标），input_value 经 connector raw 事件回传（CardKit input 的
+ * input_value 会被 SDK normalizer 丢弃，必须走 includeRawEvent 路径）。
  */
 function renderAnswerInput(requestId, questionIndex, placeholder, runId, cmd = 'approval.answerCustom') {
     // name 必须含 cmd，保证同一题同时渲染多个输入框（如单选选项题的

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

@@ -58,8 +58,9 @@ export declare function parseJumpOffset(inputValue: unknown, pageSize: number):
  * Returns an array of body elements: `[page-label div, controls column_set]`；
  * 调用方展开进 `body.elements`（+ 自己的 `hr`）。input 仍留在控件 column_set
  * 内部，不用 form 容器（form 触发 300123 / 200621 整卡不可用）。CardKit 2.0
- * input 自带 ✓ 提交图标，提交值经 raw `action.input_value` 回传，见 connector
- * includeRawEvent + router/card-action-payload.ts。
+ * input 提交（移动端键盘回车/完成键，桌面端输入框右侧提交图标）时值经 raw
+ * `action.input_value` 回传，见 connector includeRawEvent +
+ * router/card-action-payload.ts。
  *
  * 每个调用方自带 callback cmd / extra value / 文案（语义差异保留，不强行统一）。
  *
@@ -81,6 +82,41 @@ export declare function paginationBar(opts: {
     prevText?: string;
     nextText?: string;
 }): object[];
+/**
+ * 搜索输入框的组件 name（仅用于结构断言与可读性）。input 在非 form 容器下
+ * 提交值经 raw.action.input_value 回传，formValue 路径作为回退通道。
+ */
+export declare const SEARCH_INPUT_NAME = "searchInput";
+/**
+ * Build the CardKit 2.0 keyword-search row shared by /ws and /ls list cards.
+ *
+ * 飞书 input 组件没有逐键回调，只有提交（键盘回车/完成键）时才触发一次
+ * callback，所以交互是「输完回车」确认制，placeholder 必须写明。
+ *
+ * 清空输入再回车在部分客户端不可靠（用户实测：手机飞书清空后回车没反应，
+ * 空串是否发回调也没有文档保证），因此**有 `currentQuery` 就自动**在输入框
+ * 右侧补一个「清除筛选」按钮：按钮 callback 不带 input_value，handler 靠
+ * `clearQuery` 标记强制清除，不依赖「读不到输入值」这一隐式条件。
+ *
+ * 与 `paginationBar` 的控件行同一套窄屏安全模式：input 用 `weighted/weight: 1`
+ * 吃满清除按钮之外的剩余宽度，清除按钮 `auto`，手机上输入框仍可点。禁用 form
+ * 容器（300123 / 200621）与 `tag: "action"`（200861）。
+ *
+ * 返回**单个** `column_set` 元素（`paginationBar` 返回两个，调用处写法不同：
+ * `elements.push(searchBar({...}))` vs `elements.push(...paginationBar({...}))`）。
+ *
+ * @param opts.cmd         提交回调的 cmd（'ws.filter' / 'ls.filter'）。
+ * @param opts.placeholder 输入框占位文案（必须含「输完回车」）。
+ * @param opts.currentQuery 当前筛选词，非空时写进 default_value 回显，并据此
+ *                          显示「清除筛选」按钮。
+ * @param opts.extra       透传进 callback value 的附加字段（/ls 用 path/root）。
+ */
+export declare function searchBar(opts: {
+    cmd: string;
+    placeholder: string;
+    currentQuery?: string;
+    extra?: Record<string, unknown>;
+}): object;
 /**
  * Build a session-history resume card (shared by auto-restore, /resume <id>,
  * config-switch resume, and run-completion notification).

package/dist/router/card-helpers.js

@@ -104,8 +104,9 @@ export function parseJumpOffset(inputValue, pageSize) {
  * Returns an array of body elements: `[page-label div, controls column_set]`；
  * 调用方展开进 `body.elements`（+ 自己的 `hr`）。input 仍留在控件 column_set
  * 内部，不用 form 容器（form 触发 300123 / 200621 整卡不可用）。CardKit 2.0
- * input 自带 ✓ 提交图标，提交值经 raw `action.input_value` 回传，见 connector
- * includeRawEvent + router/card-action-payload.ts。
+ * input 提交（移动端键盘回车/完成键，桌面端输入框右侧提交图标）时值经 raw
+ * `action.input_value` 回传，见 connector includeRawEvent +
+ * router/card-action-payload.ts。
  *
  * 每个调用方自带 callback cmd / extra value / 文案（语义差异保留，不强行统一）。
  *
@@ -192,6 +193,82 @@ export function paginationBar(opts) {
         { tag: 'column_set', columns: controls },
     ];
 }
+/**
+ * 搜索输入框的组件 name（仅用于结构断言与可读性）。input 在非 form 容器下
+ * 提交值经 raw.action.input_value 回传，formValue 路径作为回退通道。
+ */
+export const SEARCH_INPUT_NAME = 'searchInput';
+/**
+ * Build the CardKit 2.0 keyword-search row shared by /ws and /ls list cards.
+ *
+ * 飞书 input 组件没有逐键回调，只有提交（键盘回车/完成键）时才触发一次
+ * callback，所以交互是「输完回车」确认制，placeholder 必须写明。
+ *
+ * 清空输入再回车在部分客户端不可靠（用户实测：手机飞书清空后回车没反应，
+ * 空串是否发回调也没有文档保证），因此**有 `currentQuery` 就自动**在输入框
+ * 右侧补一个「清除筛选」按钮：按钮 callback 不带 input_value，handler 靠
+ * `clearQuery` 标记强制清除，不依赖「读不到输入值」这一隐式条件。
+ *
+ * 与 `paginationBar` 的控件行同一套窄屏安全模式：input 用 `weighted/weight: 1`
+ * 吃满清除按钮之外的剩余宽度，清除按钮 `auto`，手机上输入框仍可点。禁用 form
+ * 容器（300123 / 200621）与 `tag: "action"`（200861）。
+ *
+ * 返回**单个** `column_set` 元素（`paginationBar` 返回两个，调用处写法不同：
+ * `elements.push(searchBar({...}))` vs `elements.push(...paginationBar({...}))`）。
+ *
+ * @param opts.cmd         提交回调的 cmd（'ws.filter' / 'ls.filter'）。
+ * @param opts.placeholder 输入框占位文案（必须含「输完回车」）。
+ * @param opts.currentQuery 当前筛选词，非空时写进 default_value 回显，并据此
+ *                          显示「清除筛选」按钮。
+ * @param opts.extra       透传进 callback value 的附加字段（/ls 用 path/root）。
+ */
+export function searchBar(opts) {
+    const columns = [
+        {
+            tag: 'column',
+            width: 'weighted',
+            weight: 1,
+            vertical_align: 'center',
+            elements: [
+                {
+                    tag: 'input',
+                    name: SEARCH_INPUT_NAME,
+                    placeholder: { tag: 'plain_text', content: opts.placeholder },
+                    ...(opts.currentQuery ? { default_value: opts.currentQuery } : {}),
+                    max_length: 100,
+                    behaviors: [
+                        {
+                            type: 'callback',
+                            value: { cmd: opts.cmd, ...opts.extra },
+                        },
+                    ],
+                },
+            ],
+        },
+    ];
+    if (opts.currentQuery) {
+        columns.push({
+            tag: 'column',
+            width: 'auto',
+            vertical_align: 'center',
+            elements: [
+                {
+                    tag: 'button',
+                    text: { tag: 'plain_text', content: '清除筛选' },
+                    type: 'default',
+                    size: 'small',
+                    behaviors: [
+                        {
+                            type: 'callback',
+                            value: { cmd: opts.cmd, clearQuery: true, ...opts.extra },
+                        },
+                    ],
+                },
+            ],
+        });
+    }
+    return { tag: 'column_set', columns };
+}
 /**
  * Build a session-history resume card (shared by auto-restore, /resume <id>,
  * config-switch resume, and run-completion notification).

package/dist/router/index.d.ts

@@ -61,9 +61,19 @@ export interface CardActionPayload {
     agent?: string;
     /** /resume 列表页大小覆盖。 */
     pageSize?: number;
+    /**
+     * /ws 与 /ls 列表的关键词筛选（空/缺省 = 无筛选）。服务端零状态：只随卡片
+     * callback value 传递，且仅在非空时注入，旧卡片 payload 形态不变。
+     */
+    q?: string;
+    /**
+     * 「清除筛选」按钮标记。按钮 callback 不带 input_value，但显式标记比依赖
+     * 「读不到输入值」更稳（部分客户端可能把输入框残值一并回传）。
+     */
+    clearQuery?: boolean;
     option?: string;
     formValue?: Record<string, unknown>;
-    /** CardKit 2.0 input 组件自带提交图标触发回调时回传的输入值 */
+    /** CardKit 2.0 input 组件提交（键盘回车/完成键）时回传的输入值 */
     inputValue?: string;
     orderId?: string;
     /** Approval request ID for approval card actions. */
@@ -287,6 +297,14 @@ export declare class CommandRouter {
      * Handle ls.page: paginate to a specific offset.
      */
     private handleLsPage;
+    /**
+     * Handle ls.filter: 按搜索框提交的关键词重新渲染当前目录卡。
+     *
+     * offset 恒重置为 0（新筛选从第 1 页开始）。路径校验与 TOCTOU 兜底照
+     * handleLsPage——校验失败只回错误 toast，绝不动卡片（否则用户看到一张空卡）。
+     * ls.browse / ls.switch 的 value 里刻意不带 q，换目录即清除筛选（设计文档 §2.3）。
+     */
+    private handleLsFilter;
     /**
      * Handle resume.page: paginate the /resume session list in place.
      * Mirrors handleLsPage — updates the same card, never sends a new one.
@@ -331,11 +349,12 @@ export declare class CommandRouter {
     } | null;
     /**
      * W2.8 单源：重建 order/ws 列表卡（不投递，card 进 callback 响应体用）。
+     * `q` 只服务 ws 卡的关键词筛选；order 卡无此功能，不透传。
      */
     private rebuildListCard;
     /**
      * W2.8 单源：「重建列表卡 → updateCardInPlace」原地刷新骨架（列表卡删除/
-     * 翻页/移除/排序动作共用）。返回重建后的卡片；无卡时返回 undefined 且跳过更新。
+     * 翻页/移除/排序/筛选动作共用）。返回重建后的卡片；无卡时返回 undefined 且跳过更新。
      */
     private refreshListCard;
     /**
@@ -356,7 +375,7 @@ export declare class CommandRouter {
      */
     private handleOrderPage;
     /**
-     * Handle order.aliasEdit: 展示别名编辑卡（input + ✓ 提交图标）。
+     * Handle order.aliasEdit: 展示别名编辑卡（input，回车/完成键提交）。
      * 有别名时预填；提交 `order.aliasInput` 处理（含校验与唯一性）。
      */
     /**
@@ -373,7 +392,7 @@ export declare class CommandRouter {
     /** Handle order.aliasRemove: 删除某条指令的别名并原地重渲染列表卡。 */
     private handleOrderAliasRemove;
     /**
-     * Handle order.textEdit: 展示指令文本编辑卡（input + ✓ 提交图标）。
+     * Handle order.textEdit: 展示指令文本编辑卡（input，回车/完成键提交）。
      * 预填当前 text（完整内容，不截断——input 组件有自有滚动条）；
      * 提交 `order.textInput` 处理（trim + 长度校验 + OrderStore.updateText）。
      * 完全镜像 handleOrderAliasEdit 的 4 段结构（reload → find → 构造 editCard →
@@ -408,6 +427,11 @@ export declare class CommandRouter {
      * Mirrors handleOrderPage — updates the same card, never sends a new one.
      */
     private handleWsPage;
+    /**
+     * Handle ws.filter: 按搜索框提交的关键词重新渲染列表卡。
+     * offset 恒重置为 0（新筛选从第 1 页开始）；提交空串 = 清除筛选。
+     */
+    private handleWsFilter;
     /**
      * Handle ws.sort: toggle sort preference and refresh the /ws list card.
      * Sort preference is memory-only (not persisted); restart resets to 'recent'.
@@ -531,8 +555,10 @@ export declare class CommandRouter {
      * @param rootDir 浏览起点：卡片「返回」按钮回到这里。省略时默认 = 本次列出的
      *                目录（`/ls <dir>` 的起点即该目录），因此「返回」不会把用户
      *                丢回 workspace cwd（用户明确反馈过）。
+     * @param q       关键词筛选：只匹配**当前层**条目名（不递归），大小写不敏感。
+     *                省略/空 = 无筛选。
      */
-    cmdLs(args: string[], ctx: CommandContext, offset?: number, rootDir?: string): CommandResult;
+    cmdLs(args: string[], ctx: CommandContext, offset?: number, rootDir?: string, q?: string): CommandResult;
     /**
      * `/download <path>`（别名 `/d`）：把本地文件直接发送到飞书。
      *
@@ -547,7 +573,14 @@ export declare class CommandRouter {
      * 此前直接回 `ls: xxx: Not a directory` 把文件路径当成错误处理。
      */
     private buildFileCard;
-    private cmdWs;
+    /**
+     * `/ws` 实现（public：测试直接调用，替代 as unknown as，与 cmdLs 同款）。
+     *
+     * @param offset list 分支的分页起点（条目数）
+     * @param q      list 分支的关键词筛选：name 或完整 path 命中即保留，大小写
+     *               不敏感。省略/空 = 无筛选。
+     */
+    cmdWs(args: string[], ctx: CommandContext, offset?: number, q?: string): CommandResult;
     /**
      * L3: degraded card when a session's export is non-empty but unparseable
      * (truncated by opencode's pipe cap on huge sessions, or otherwise corrupt).

package/dist/router/index.js

@@ -11,7 +11,7 @@ import { diffConfig, setNestedValue } from './config-diff.js';
 import { getLogger } from '../logger/index.js';
 import { stripPlaceholders } from '../inbound/placeholder.js';
 import { activeRunUsage, clampInt } from './utils.js';
-import { markdownDiv, buildSessionHistoryCard, paginationBar, parseJumpOffset, PAGE_JUMP_INVALID_HINT, } from './card-helpers.js';
+import { markdownDiv, buildSessionHistoryCard, paginationBar, searchBar, parseJumpOffset, SEARCH_INPUT_NAME, PAGE_JUMP_INVALID_HINT, } from './card-helpers.js';
 import { MAX_FILE_UPLOAD_SIZE } from '../connector/file-limits.js';
 import { atomicWrite } from '../persistence/atomic-write.js';
 import { checkLatestVersion as defaultCheckLatestVersion, isNewer as defaultIsNewer, runInstallLatest as defaultRunInstallLatest, } from '../update/index.js';
@@ -290,9 +290,11 @@ const IMMEDIATE_ACTION_CMDS = new Set([
     'ls.browse',
     'ls.switch',
     'ls.page', // control operation: paginate only, never spawns claude
+    'ls.filter', // control operation: refilter the /ls list only
     'resume.page', // control operation: paginate only, never spawns claude
     'active.page', // control operation: paginate active card
     'ws.page', // control operation: paginate /ws list only
+    'ws.filter', // control operation: refilter the /ws list only
     'ws.remove',
     'ws.sort', // control operation: toggle sort mode only
     'resume.use',
@@ -322,6 +324,19 @@ const IMMEDIATE_ACTION_CMDS = new Set([
 function payloadOffset(value) {
     return Math.max(0, Math.trunc(Number(value.offset) || 0));
 }
+/**
+ * 搜索框提交值单源读取：`inputValue` 主路（CardKit 2.0 input 提交（键盘回车/
+ * 完成键）经 raw `action.input_value` 回传，SDK normalizer 会丢弃
+ * `action.input_value`，依赖 connector 的 includeRawEvent）+
+ * `formValue[searchInput]` 回退。空串/纯空白一律归一为 undefined = 清除筛选，
+ * 不是报错也不是无操作。「清除筛选」按钮带 `clearQuery`，直接短路为 undefined。
+ */
+function searchQueryFrom(value) {
+    if (value.clearQuery)
+        return undefined;
+    const raw = value.inputValue ?? value.formValue?.[SEARCH_INPUT_NAME];
+    return raw?.trim() || undefined;
+}
 /** 卡片 cardAction payload 缺字段的统一报错文案（原先 12 处手写且已漂移出两种前缀）。 */
 const CARD_PAYLOAD_MISSING = '⚠️ 卡片 payload 缺少必要信息';
 export class CommandRouter {
@@ -524,8 +539,12 @@ export class CommandRouter {
                 return;
             case 'ls.page':
                 return this.handleLsPage(value, ctx);
+            case 'ls.filter':
+                return this.handleLsFilter(value, ctx);
             case 'ws.page':
                 return this.handleWsPage(value, ctx);
+            case 'ws.filter':
+                return this.handleWsFilter(value, ctx);
             case 'ws.use':
                 return await this.handleWsUse(value, ctx);
             case 'ws.sort':
@@ -932,7 +951,7 @@ export class CommandRouter {
             return;
         }
         // Build edit card
-        // CardKit 2.0 input 自带 ✓ 提交图标，点击时输入值走 raw.action.input_value
+        // CardKit 2.0 input 提交（回车/完成键）时输入值走 raw.action.input_value
         // （SDK normalizer 丢弃，需 connector includeRawEvent: true + index.ts 从 raw 提取）。
         // 用 column_set + input + behaviors，不用 form 容器（form 触发 300123 无 submit button /
         // 200621 嵌套 column，submit-typed button 也被 CardKit 2.0 拒绝 HTTP 400）。
@@ -952,7 +971,7 @@ export class CommandRouter {
                     { tag: 'hr' },
                     {
                         tag: 'div',
-                        text: { tag: 'lark_md', content: '💡 输入新内容后点击右侧 ✓ 提交图标' },
+                        text: { tag: 'lark_md', content: '💡 输入新内容后按回车提交' },
                     },
                     {
                         tag: 'column_set',
@@ -1126,11 +1145,11 @@ export class CommandRouter {
         try {
             card =
                 targetPath && fs.existsSync(targetPath) && fs.statSync(targetPath).isDirectory()
-                    ? this.cmdLs([targetPath], ctx, offset, value.root)
-                    : this.cmdLs([], ctx, offset, value.root);
+                    ? this.cmdLs([targetPath], ctx, offset, value.root, value.q)
+                    : this.cmdLs([], ctx, offset, value.root, value.q);
         }
         catch {
-            card = this.cmdLs([], ctx, offset, value.root);
+            card = this.cmdLs([], ctx, offset, value.root, value.q);
         }
         await this.bridge.updateCardInPlace(card.card, ctx);
     }
@@ -1160,11 +1179,39 @@ export class CommandRouter {
         if (!isDir) {
             return { toast: { type: 'error', content: `路径无效: ${resolvedTarget}` } };
         }
-        const card = this.cmdLs([resolvedTarget], ctx, paging.offset, value.root);
+        const card = this.cmdLs([resolvedTarget], ctx, paging.offset, value.root, value.q);
         // 直接更新卡片，与 ls.browse/ls.refresh 行为一致
         await this.bridge.updateCardInPlace(card.card, ctx);
         return { toast: { type: 'success', content: '' } };
     }
+    /**
+     * Handle ls.filter: 按搜索框提交的关键词重新渲染当前目录卡。
+     *
+     * offset 恒重置为 0（新筛选从第 1 页开始）。路径校验与 TOCTOU 兜底照
+     * handleLsPage——校验失败只回错误 toast，绝不动卡片（否则用户看到一张空卡）。
+     * ls.browse / ls.switch 的 value 里刻意不带 q，换目录即清除筛选（设计文档 §2.3）。
+     */
+    async handleLsFilter(value, ctx) {
+        const targetPath = value.path;
+        if (!targetPath) {
+            return { toast: { type: 'error', content: '卡片 payload 缺少 path' } };
+        }
+        const q = searchQueryFrom(value);
+        const resolvedTarget = path.resolve(targetPath);
+        let isDir;
+        try {
+            isDir = fs.existsSync(resolvedTarget) && fs.statSync(resolvedTarget).isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+        if (!isDir) {
+            return { toast: { type: 'error', content: `路径无效: ${resolvedTarget}` } };
+        }
+        const card = this.cmdLs([resolvedTarget], ctx, 0, value.root, q);
+        await this.bridge.updateCardInPlace(card.card, ctx);
+        return { toast: { type: 'success', content: q ? `筛选："${q}"` : '已清除筛选' } };
+    }
     /**
      * Handle resume.page: paginate the /resume session list in place.
      * Mirrors handleLsPage — updates the same card, never sends a new one.
@@ -1287,18 +1334,19 @@ export class CommandRouter {
     }
     /**
      * W2.8 单源：重建 order/ws 列表卡（不投递，card 进 callback 响应体用）。
+     * `q` 只服务 ws 卡的关键词筛选；order 卡无此功能，不透传。
      */
-    rebuildListCard(kind, offset, ctx) {
-        return kind === 'order'
-            ? this.cmdOrder([], ctx, offset).card
-            : this.cmdWs([], ctx, offset).card;
+    rebuildListCard(kind, offset, ctx, q) {
+        if (kind === 'order')
+            return this.cmdOrder([], ctx, offset).card;
+        return this.cmdWs([], ctx, offset, q).card;
     }
     /**
      * W2.8 单源：「重建列表卡 → updateCardInPlace」原地刷新骨架（列表卡删除/
-     * 翻页/移除/排序动作共用）。返回重建后的卡片；无卡时返回 undefined 且跳过更新。
+     * 翻页/移除/排序/筛选动作共用）。返回重建后的卡片；无卡时返回 undefined 且跳过更新。
      */
     async refreshListCard(kind, value, ctx) {
-        const card = this.rebuildListCard(kind, payloadOffset(value), ctx);
+        const card = this.rebuildListCard(kind, payloadOffset(value), ctx, value.q);
         if (!card)
             return undefined;
         await this.bridge.updateCardInPlace(card, ctx);
@@ -1361,7 +1409,7 @@ export class CommandRouter {
         return { toast: { type: 'success', content: '' } };
     }
     /**
-     * Handle order.aliasEdit: 展示别名编辑卡（input + ✓ 提交图标）。
+     * Handle order.aliasEdit: 展示别名编辑卡（input，回车/完成键提交）。
      * 有别名时预填；提交 `order.aliasInput` 处理（含校验与唯一性）。
      */
     /**
@@ -1381,7 +1429,7 @@ export class CommandRouter {
         }
         // 列表卡显示的是截断版（≤100 字符 + ...），编辑卡预览保持一致
         const displayText = order.text.length > 100 ? order.text.slice(0, 97) + '...' : order.text;
-        // CardKit 2.0 input 自带 ✓ 提交图标（input_value 经 raw 回传，红线）。
+        // CardKit 2.0 input 提交（回车/完成键；input_value 经 raw 回传，红线）。
         // 不用 form 容器（触发 300123 无 submit button / 200621 嵌套 column）。
         const editCard = {
             schema: '2.0',
@@ -1436,7 +1484,7 @@ export class CommandRouter {
         const order = this.orderStore.get().find((o) => o.id === value.orderId);
         return this.showOrderEditCard(value, ctx, {
             title: '✏️ 给指令起别名',
-            hint: '💡 输入别名名后点击右侧 ✓ 提交；留空提交 = 删除该别名',
+            hint: '💡 输入别名名后按回车提交；删除别名请点列表卡别名旁的 ✕',
             inputName: 'aliasName',
             placeholder: '输入 $别名名（如 all）...',
             defaultValue: order?.alias ?? '',
@@ -1480,7 +1528,7 @@ export class CommandRouter {
         });
     }
     /**
-     * Handle order.textEdit: 展示指令文本编辑卡（input + ✓ 提交图标）。
+     * Handle order.textEdit: 展示指令文本编辑卡（input，回车/完成键提交）。
      * 预填当前 text（完整内容，不截断——input 组件有自有滚动条）；
      * 提交 `order.textInput` 处理（trim + 长度校验 + OrderStore.updateText）。
      * 完全镜像 handleOrderAliasEdit 的 4 段结构（reload → find → 构造 editCard →
@@ -1492,7 +1540,7 @@ export class CommandRouter {
         // input 组件 default_value 预填完整 text（不受截断影响），提交后生效完整文本
         return this.showOrderEditCard(value, ctx, {
             title: '✏️ 编辑指令',
-            hint: '💡 修改后点击右侧 ✓ 提交；空白提交 = 报错；最多 200 字符',
+            hint: '💡 修改后按回车提交；空白提交 = 报错；最多 200 字符',
             inputName: 'text',
             placeholder: '输入新的指令文本...',
             defaultValue: order?.text ?? '',
@@ -1594,9 +1642,18 @@ export class CommandRouter {
             return { toast: { type: 'error', content: paging.error } };
         }
         // cmdWs internally clamps stale/out-of-range offsets
-        await this.refreshListCard('ws', { offset: paging.offset }, ctx);
+        await this.refreshListCard('ws', { offset: paging.offset, q: value.q }, ctx);
         return { toast: { type: 'success', content: '' } };
     }
+    /**
+     * Handle ws.filter: 按搜索框提交的关键词重新渲染列表卡。
+     * offset 恒重置为 0（新筛选从第 1 页开始）；提交空串 = 清除筛选。
+     */
+    async handleWsFilter(value, ctx) {
+        const q = searchQueryFrom(value);
+        await this.refreshListCard('ws', { offset: 0, q }, ctx);
+        return { toast: { type: 'success', content: q ? `筛选："${q}"` : '已清除筛选' } };
+    }
     /**
      * Handle ws.sort: toggle sort preference and refresh the /ws list card.
      * Sort preference is memory-only (not persisted); restart resets to 'recent'.
@@ -1606,7 +1663,7 @@ export class CommandRouter {
         const current = this.wsSortPreference.get(userId) ?? 'recent';
         const next = current === 'recent' ? 'alpha' : 'recent';
         this.wsSortPreference.set(userId, next);
-        await this.refreshListCard('ws', { offset: 0 }, ctx);
+        await this.refreshListCard('ws', { offset: 0, q: value.q }, ctx);
         const nextLabel = next === 'recent' ? '🕐 最近使用' : '🔤 字母顺序';
         return {
             toast: { type: 'success', content: `已切换为 ${nextLabel}` },
@@ -1741,7 +1798,7 @@ export class CommandRouter {
             }
             case 'config.input': {
                 // Handle input field: value.key is the field key.
-                // 2026-07-04: CardKit 2.0 input 自带提交图标触发 callback，回传 input_value。
+                // 2026-07-04: CardKit 2.0 input 提交（回车/完成键）触发 callback，回传 input_value。
                 // Fall back to formValue[key]: the SDK currently reports input values
                 // via action.formValue for form-wrapped inputs.
                 const key = value.key;
@@ -2609,12 +2666,15 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
      * @param rootDir 浏览起点：卡片「返回」按钮回到这里。省略时默认 = 本次列出的
      *                目录（`/ls <dir>` 的起点即该目录），因此「返回」不会把用户
      *                丢回 workspace cwd（用户明确反馈过）。
+     * @param q       关键词筛选：只匹配**当前层**条目名（不递归），大小写不敏感。
+     *                省略/空 = 无筛选。
      */
-    cmdLs(args, ctx, offset = 0, rootDir) {
+    cmdLs(args, ctx, offset = 0, rootDir, q) {
         const cwd = this.sessionStore.getCwd(ctx.userId);
         if (!cwd) {
             return { text: '请先使用 /cd <path> 设置工作目录' };
         }
+        const filter = q?.trim() || undefined;
         // args can be:
         // - [] : list current cwd
         // - [dirName] : list subdirectory if it exists
@@ -2665,8 +2725,16 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                     size: fs.statSync(path.join(targetDir, f.name)).size,
                 })),
             ];
+            // 关键词筛选：只匹配当前层条目名（不递归子目录）。大小写不敏感的子串包含
+            // ——禁止 new RegExp(q)（用户搜 `foo(` 会直接抛）。插在排序之后、分页之前。
+            const ql = filter?.toLowerCase();
+            const visibleItems = ql
+                ? allItems.filter((i) => i.name.toLowerCase().includes(ql))
+                : allItems;
+            const visibleDirCount = visibleItems.reduce((n, i) => n + (i.isDir ? 1 : 0), 0);
+            const visibleFileCount = visibleItems.length - visibleDirCount;
             // Pagination calculations（clamp 到最后一页边界，原先不 clamp 会显示空页）
-            const { totalCount, totalPages, safeOffset, currentPage, pageItems, hasPagination } = pageSlice(allItems, offset, CommandRouter.LS_PAGE_SIZE);
+            const { totalCount, totalPages, safeOffset, currentPage, pageItems, hasPagination } = pageSlice(visibleItems, offset, CommandRouter.LS_PAGE_SIZE);
             // Check if we need to show parent directory button
             const parentDir = path.dirname(targetDir);
             const hasParent = parentDir !== targetDir;
@@ -2712,6 +2780,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                             path: targetDir,
                             offset: safeOffset,
                             root: browseRoot,
+                            ...(filter ? { q: filter } : {}),
                         },
                     },
                 ],
@@ -2763,8 +2832,9 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             // Note: div+elements is not supported in CardKit 2.0, use column_set instead
             const elements = [];
             // Status line：只报条目构成；页码/总数交给分页栏文案行（同一信息不重复
-            // 渲染两遍——2026-09-10 分页栏改成整行文案后重复会很明显）。
-            const status = `\n共 ${dirs.length} 目录, ${files.length} 文件`;
+            // 渲染两遍——2026-09-10 分页栏改成整行文案后重复会很明显）。筛选态一律用
+            // 过滤后的计数，否则标题说 12 项、列表只有 3 项，卡片自相矛盾。
+            const status = `\n共 ${visibleDirCount} 目录, ${visibleFileCount} 文件`;
             // Header info + navigation buttons - show targetDir in header
             elements.push({ tag: 'div', text: { tag: 'lark_md', content: `\`${targetDir}\`${status}` } });
             elements.push({
@@ -2772,54 +2842,81 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 columns: headerElements.map((e) => ({ tag: 'column', width: 'auto', elements: [e] })),
             });
             elements.push({ tag: 'hr' });
-            // Section 1: Directories (show only items on current page)
+            // 搜索行：头部导航按钮之下、内容区之上（主导航在上、过滤紧随其后、内容区
+            // 在下）。path/root 必须进 callback value，否则提交后 handler 不知道刷哪。
+            elements.push(searchBar({
+                cmd: 'ls.filter',
+                placeholder: '搜索本层目录/文件名，输完回车',
+                currentQuery: filter,
+                extra: { path: targetDir, root: browseRoot },
+            }));
+            if (filter) {
+                elements.push({
+                    tag: 'div',
+                    text: {
+                        tag: 'lark_md',
+                        content: `🔍 筛选："${filter}" · 命中 ${totalCount} 项（点「清除筛选」取消）`,
+                    },
+                });
+            }
+            // Section 1 + 2: Directories / Files (show only items on current page)
             const pageDirs = pageItems.filter((i) => i.isDir);
             const pageFiles = pageItems.filter((i) => !i.isDir);
-            elements.push({
-                tag: 'div',
-                text: { tag: 'lark_md', content: `**📂 目录 (${dirs.length})**` },
-            });
-            if (pageDirs.length > 0) {
-                for (const d of pageDirs) {
-                    elements.push({
-                        tag: 'column_set',
-                        flex_mode: 'none',
-                        columns: [{ tag: 'column', width: 'auto', elements: [dirButton(d.name)] }],
-                    });
-                }
-            }
-            else if (dirs.length === 0) {
-                elements.push({ tag: 'div', text: { tag: 'lark_md', content: '无子目录' } });
+            if (filter && visibleItems.length === 0) {
+                // 筛选零命中：两个区标题都不渲染（两行空区标题只是噪音），搜索行仍在，
+                // 用户可直接改词再回车，或点「清除筛选」。
+                elements.push({
+                    tag: 'div',
+                    text: { tag: 'lark_md', content: `🔍 无匹配条目（关键词："${filter}"）` },
+                });
             }
             else {
                 elements.push({
                     tag: 'div',
-                    text: { tag: 'lark_md', content: `（第 ${currentPage} 页无目录）` },
+                    text: { tag: 'lark_md', content: `**📂 目录 (${visibleDirCount})**` },
                 });
-            }
-            elements.push({ tag: 'hr' });
-            // Section 2: Files
-            elements.push({
-                tag: 'div',
-                text: { tag: 'lark_md', content: `**📄 文件 (${files.length})**` },
-            });
-            if (pageFiles.length > 0) {
-                for (const f of pageFiles) {
+                if (pageDirs.length > 0) {
+                    for (const d of pageDirs) {
+                        elements.push({
+                            tag: 'column_set',
+                            flex_mode: 'none',
+                            columns: [{ tag: 'column', width: 'auto', elements: [dirButton(d.name)] }],
+                        });
+                    }
+                }
+                else if (visibleDirCount === 0) {
+                    elements.push({ tag: 'div', text: { tag: 'lark_md', content: '无子目录' } });
+                }
+                else {
                     elements.push({
-                        tag: 'column_set',
-                        flex_mode: 'none',
-                        columns: [{ tag: 'column', width: 'auto', elements: [fileButton(f.name, f.size)] }],
+                        tag: 'div',
+                        text: { tag: 'lark_md', content: `（第 ${currentPage} 页无目录）` },
                     });
                 }
-            }
-            else if (files.length === 0) {
-                elements.push({ tag: 'div', text: { tag: 'lark_md', content: '无文件' } });
-            }
-            else {
+                elements.push({ tag: 'hr' });
+                // Section 2: Files
                 elements.push({
                     tag: 'div',
-                    text: { tag: 'lark_md', content: `（第 ${currentPage} 页无文件）` },
+                    text: { tag: 'lark_md', content: `**📄 文件 (${visibleFileCount})**` },
                 });
+                if (pageFiles.length > 0) {
+                    for (const f of pageFiles) {
+                        elements.push({
+                            tag: 'column_set',
+                            flex_mode: 'none',
+                            columns: [{ tag: 'column', width: 'auto', elements: [fileButton(f.name, f.size)] }],
+                        });
+                    }
+                }
+                else if (visibleFileCount === 0) {
+                    elements.push({ tag: 'div', text: { tag: 'lark_md', content: '无文件' } });
+                }
+                else {
+                    elements.push({
+                        tag: 'div',
+                        text: { tag: 'lark_md', content: `（第 ${currentPage} 页无文件）` },
+                    });
+                }
             }
             // Pagination bar (only shown when there are more items than PAGE_SIZE)
             if (hasPagination) {
@@ -2828,7 +2925,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                     offset: safeOffset,
                     pageSize: CommandRouter.LS_PAGE_SIZE,
                     total: totalCount,
-                    extra: { path: targetDir, root: browseRoot },
+                    extra: { path: targetDir, root: browseRoot, ...(filter ? { q: filter } : {}) },
                     label: `**第 ${currentPage}/${totalPages} 页**（共 ${totalCount} 项）`,
                 });
                 elements.push({ tag: 'hr' });
@@ -2945,7 +3042,14 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             },
         };
     }
-    cmdWs(args, ctx, offset = 0) {
+    /**
+     * `/ws` 实现（public：测试直接调用，替代 as unknown as，与 cmdLs 同款）。
+     *
+     * @param offset list 分支的分页起点（条目数）
+     * @param q      list 分支的关键词筛选：name 或完整 path 命中即保留，大小写
+     *               不敏感。省略/空 = 无筛选。
+     */
+    cmdWs(args, ctx, offset = 0, q) {
         const sub = args[0]?.toLowerCase();
         switch (sub) {
             case 'save': {
@@ -2994,6 +3098,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             }
             case 'list':
             default: {
+                const filter = q?.trim() || undefined;
                 const entries = this.workspaceStore.list();
                 const currentCwd = this.sessionStore.getCwd(ctx.userId);
                 const sortMode = this.wsSortPreference.get(ctx.userId) ?? 'recent';
@@ -3010,9 +3115,16 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                     // Alphabetical by alias name
                     entries.sort((a, b) => a.name.localeCompare(b.name));
                 }
+                // 关键词筛选：alias name 或完整 path 命中即保留，大小写不敏感的子串包含
+                // （禁止 new RegExp(q)——用户搜 `foo(` 会直接抛）。插在排序之后、分页
+                // 之前：先分页再过滤会出现某页只剩 1 条的残页，且翻页时筛选像是丢了。
+                const ql = filter?.toLowerCase();
+                const visible = ql
+                    ? entries.filter((e) => e.name.toLowerCase().includes(ql) || e.path.toLowerCase().includes(ql))
+                    : entries;
                 // Pagination calculations (mirror cmdOrder): clamp stale/out-of-range
                 // offsets so prev/next always step by WS_PAGE_SIZE.
-                const { totalCount, totalPages, safeOffset, currentPage, pageItems: pageEntries, hasPagination, } = pageSlice(entries, offset, WS_PAGE_SIZE);
+                const { totalCount, totalPages, safeOffset, currentPage, pageItems: pageEntries, hasPagination, } = pageSlice(visible, offset, WS_PAGE_SIZE);
                 // Build body elements: current cwd + workspace list with dividers
                 const bodyElements = [];
                 // Current working directory section
@@ -3020,13 +3132,35 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                     tag: 'div',
                     text: { tag: 'lark_md', content: `📂 当前工作目录：\`${currentCwd ?? '(未设置)'}\`` },
                 });
-                if (entries.length === 0) {
-                    bodyElements.push({ tag: 'hr' });
+                bodyElements.push({ tag: 'hr' });
+                // 搜索行：「当前工作目录」之下、排序行之上（与 /ls 同一视觉动线：主信息
+                // 在上、过滤紧随其后、列表在下）
+                bodyElements.push(searchBar({
+                    cmd: 'ws.filter',
+                    placeholder: '搜索名称或路径，输完回车',
+                    currentQuery: filter,
+                }));
+                if (filter) {
+                    bodyElements.push({
+                        tag: 'div',
+                        text: {
+                            tag: 'lark_md',
+                            content: `🔍 筛选："${filter}" · 命中 ${totalCount} 个 workspace（点「清除筛选」取消）`,
+                        },
+                    });
+                }
+                if (entries.length === 0 && !filter) {
                     bodyElements.push({
                         tag: 'div',
                         text: { tag: 'lark_md', content: '没有保存的 workspace' },
                     });
                 }
+                else if (filter && visible.length === 0) {
+                    bodyElements.push({
+                        tag: 'div',
+                        text: { tag: 'lark_md', content: `🔍 无匹配条目（关键词："${filter}"）` },
+                    });
+                }
                 else {
                     // Sort mode indicator + toggle button: placed above the list so the user
                     // sees "current mode" and "switch to X" before scanning entries.
@@ -3059,7 +3193,12 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                                         text: { tag: 'plain_text', content: `切换为 ${switchLabel}` },
                                         type: 'default',
                                         size: 'small',
-                                        behaviors: [{ type: 'callback', value: { cmd: 'ws.sort' } }],
+                                        behaviors: [
+                                            {
+                                                type: 'callback',
+                                                value: { cmd: 'ws.sort', ...(filter ? { q: filter } : {}) },
+                                            },
+                                        ],
                                     },
                                 ],
                             },
@@ -3087,7 +3226,12 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                                             behaviors: [
                                                 {
                                                     type: 'callback',
-                                                    value: { cmd: 'ws.use', name: entry.name, offset: safeOffset },
+                                                    value: {
+                                                        cmd: 'ws.use',
+                                                        name: entry.name,
+                                                        offset: safeOffset,
+                                                        ...(filter ? { q: filter } : {}),
+                                                    },
                                                 },
                                             ],
                                         },
@@ -3105,7 +3249,12 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                                             behaviors: [
                                                 {
                                                     type: 'callback',
-                                                    value: { cmd: 'ws.remove', name: entry.name, offset: safeOffset },
+                                                    value: {
+                                                        cmd: 'ws.remove',
+                                                        name: entry.name,
+                                                        offset: safeOffset,
+                                                        ...(filter ? { q: filter } : {}),
+                                                    },
                                                 },
                                             ],
                                         },
@@ -3124,6 +3273,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                             offset: safeOffset,
                             pageSize: WS_PAGE_SIZE,
                             total: totalCount,
+                            extra: filter ? { q: filter } : {},
                             label: `**${currentPage}/${totalPages}**（${totalCount}）`,
                             prevText: '⬅',
                             nextText: '➡',
@@ -3836,7 +3986,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                                                 ],
                                             },
                                             {
-                                                // 编辑：弹蓝色 header 输入卡（CardKit 2.0 input + ✓ 提交），
+                                                // 编辑：弹蓝色 header 输入卡（CardKit 2.0 input，回车提交），
                                                 // 镜像 order.aliasEdit 流程。order.textEdit 是 control-only action
                                                 // （isImmediateAction 注册），不 spawn agent。
                                                 tag: 'column',

package/dist/runner/dsh/fake-dsh-server.d.ts

@@ -48,6 +48,12 @@ export declare class FakeDshServer {
     setMuxFrames(frames: Array<object | {
         close: true;
     }>): void;
+    /** Append a single frame at response time (real DSH only produces a turn's
+     *  events after accepting its prompt) — avoids pre-queued frames racing a
+     *  previous run's still-closing mux subscription. */
+    pushMuxFrame(frame: object | {
+        close: true;
+    }): void;
     setHistoryValue(value: unknown): void;
     /** Synchronous unary dispatch (no HTTP) — used by tests that inject the
      *  reader's sync transport to avoid the spawnSync-in-process deadlock. */

package/dist/runner/dsh/fake-dsh-server.js

@@ -95,6 +95,12 @@ export class FakeDshServer {
     setMuxFrames(frames) {
         this.muxFrames = frames;
     }
+    /** Append a single frame at response time (real DSH only produces a turn's
+     *  events after accepting its prompt) — avoids pre-queued frames racing a
+     *  previous run's still-closing mux subscription. */
+    pushMuxFrame(frame) {
+        this.muxFrames.push(frame);
+    }
     setHistoryValue(value) {
         this.historyValue = value;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lark-remote",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Feishu (Lark) private-chat bridge to local coding agents — Claude Code / Codex / opencode / pi / kimi, with live-streaming CardKit 2.0 cards",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",