lark-remote 0.4.0 → 0.4.2

package/dist/index.js

@@ -24,6 +24,8 @@ import { startSleepBlocker } from './platform/sleep-blocker.js';
 import { checkLatestVersion, isNewer, runInstallLatest, formatUpdateHint } from './update/index.js';
 import { classifyRejection } from './error-classification.js';
 import { WorkspaceStore } from './workspace/index.js';
+import { InboundTurnAssembler } from './inbound/turn-assembler.js';
+import { stripPlaceholders } from './inbound/placeholder.js';
 import { buildSessionHistoryCard } from './router/card-helpers.js';
 import { newSessionButton, resumeCompactButton, agentDisplayName } from './card/card-shared.js';
 import path from 'node:path';
@@ -197,6 +199,12 @@ function initializeRunner(config, configDir, cliArgs) {
             model,
             sessionReader: opencodeSessionReader,
             mode: ocConfig?.mode ?? 'build',
+            binary: ocConfig?.acp?.binary,
+            requestTimeoutMs: ocConfig?.acp?.requestTimeoutMs,
+            idleTtlMs: ocConfig?.acp?.idleTtlMs,
+            turnIdleTimeoutMs: ocConfig?.acp?.turnIdleTimeoutMinutes != null
+                ? ocConfig.acp.turnIdleTimeoutMinutes * 60_000
+                : undefined,
         });
     });
     sessionReaderRegistry.register('opencode', opencodeSessionReader);
@@ -292,9 +300,48 @@ function initializeRunner(config, configDir, cliArgs) {
 }
 /** Setup message and card action handlers. */
 function setupMessageHandlers(connector, router, bridge, sessionStore, workspaceStore, binder, logger, config, cloneSession) {
-    // 入站媒体（图片/文件）：先认证后下载（P1 review 修复）。
+    // 入站统一装配器（2026-09-15）：图/文任意顺序 → 同一个 turn、同一个 prompt，
+    // 附件路径统一注入 prompt；无文本纯附件只回执（决策 2）。
+    const assembler = new InboundTurnAssembler({
+        onCommit: (turn, prompt) => {
+            // 入队时刻（T0）快照 workspace + agent/session 绑定，语义与旧路径一致
+            // （排队期间 /cd、/config 不再导致语义漂移）。
+            const messageId = turn.messageIds[turn.messageIds.length - 1] ?? '';
+            const ctx = { userId: turn.userId, chatId: turn.chatId, messageId };
+            let workspace = sessionStore.getCwd(turn.userId) ?? '';
+            if (!workspace && workspaceStore) {
+                const workspaces = workspaceStore.list();
+                if (workspaces.length > 0)
+                    workspace = workspaces[0].path;
+            }
+            const binding = bridge.currentBinding(turn.userId);
+            bridge.enqueue(workspace, async () => {
+                // allowCommandPrefix: false —— prompt 已剥离占位符，绝不再做命令分发。
+                await router.handle(prompt, ctx, {
+                    cwdOverride: workspace,
+                    binding,
+                    allowCommandPrefix: false,
+                });
+            }, {
+                taskMeta: {
+                    userId: turn.userId,
+                    chatId: turn.chatId,
+                    messageId,
+                    messagePreview: prompt.slice(0, 3000),
+                    binding,
+                },
+            });
+        },
+        onReceipt: async (ctx, text) => {
+            await bridge.sendResult({ text }, ctx);
+        },
+    });
+    router.setInboundFlusher(() => assembler.flushAll('flush'));
+    // 入站媒体（图片/文件/视频/语音/表情）：先认证后下载（P1 review 修复）。
     // connector 只上报"媒体到达"，这里先过 owner + enabled 闸门，通过后才
     // 下载——未认证/关闭配置时不会发生任何网络下载或内存/磁盘占用。
+    // 下载是异步的：立刻把在途 promise 交给装配器（`kind: 'media'`），
+    // 保证「先图后文」不会先提交一个只含文本的 turn。
     connector.setInboundMediaDetectedHandler((msg) => {
         if (!binder.isOwner(msg.userId)) {
             logger.warn(`[media] rejected inbound media from non-owner ${msg.userId}`);
@@ -304,35 +351,45 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
         // 启动时捕获的 config 参数会过期（P2 review 修复）。
         if (!router.config.inboundMedia.enabled) {
             // 不静默（P3 review）：关闭时给 owner 明确反馈，避免发图后无任何反应。
-            // 不下载、不落盘，只回一条说明。
-            void bridge
-                .sendResult({
-                text: '⚠️ 入站媒体保存已关闭（inboundMedia.enabled: false），未保存文件。' +
-                    '如需自动保存图片/文件，请开启后重试',
-            }, {
+            // 不下载、不落盘，只进 rejected（随 turn 回执一起发出）。
+            assembler.ingest({
+                kind: 'rejected',
                 userId: msg.userId,
                 chatId: msg.chatId,
                 messageId: msg.messageId,
-            })
-                .catch((err) => logger.error('[media] disabled feedback send failed:', err));
+                replyToMessageId: msg.replyToMessageId,
+                rawContentType: msg.rawContentType,
+                rejectedKind: 'file',
+                reason: '入站媒体保存已关闭（inboundMedia.enabled: false），未保存文件。' +
+                    '如需自动保存图片/文件，请开启后重试',
+            });
             return;
         }
-        void (async () => {
+        const outcome = (async () => {
             const payload = await connector.downloadInboundMedia(msg, {
                 maxFileSizeMb: router.config.inboundMedia.maxFileSizeMb,
             });
             try {
-                await bridge.onInboundMedia(payload);
+                return await bridge.saveInboundMedia(payload);
             }
             catch (err) {
-                // handle() 的正常路径会清理临时文件；这里兜底 handle 进入 mkdir
+                // save() 的正常路径会清理临时文件；这里兜底 save 进入 mkdir
                 // try 之前意外抛错的情况，避免 os.tmpdir 残留。
                 for (const item of payload.media) {
                     silentlyUnlink(item.tempPath);
                 }
                 throw err;
             }
-        })().catch((err) => logger.error('[media] inbound media download/save failed:', err));
+        })();
+        assembler.ingest({
+            kind: 'media',
+            userId: msg.userId,
+            chatId: msg.chatId,
+            messageId: msg.messageId,
+            replyToMessageId: msg.replyToMessageId,
+            rawContentType: msg.rawContentType,
+            outcome,
+        });
     });
     connector.setMessageHandler((msg) => {
         // 绑定/授权闸门：仅 owner 放行；非 owner 静默丢弃；未绑定时首条消息（任意内容）认领
@@ -387,10 +444,7 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
             return;
         }
         // decision.kind === 'owner'：正常处理（不再每条覆盖 startup-contact）
-        logger.info(`message from ${msg.userId}: ${msg.content.slice(0, 100)}`);
-        // 文本到达先冲刷待合批的媒体保存提示（先图后文字时文字到达
-        // 先冲刷批次，避免合批提示被后续消息淹没/丢图）。
-        bridge.flushMediaNotifications(msg.userId, msg.chatId);
+        logger.info(`message from ${msg.userId} (${msg.rawContentType}): ${msg.content.slice(0, 100)}`);
         // Add Typing reaction to indicate "still alive"
         void connector.addReaction(msg.messageId, 'Typing');
         // 复制分身流程活跃期：一切消息先经 clone 状态机（stop 命令除外，保留其
@@ -425,67 +479,38 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
             })().catch((err) => logger.error('[control] /stop failed:', err));
             return;
         }
-        if (content.trim().startsWith('/')) {
-            void router
-                .handle(content, {
-                userId: msg.userId,
-                chatId: msg.chatId,
-                messageId: msg.messageId,
-            })
-                .catch((err) => logger.error('[control] slash command failed:', err));
-            return;
+        // 先清洗，后判语义（§5.6）：结构占位符永远不能触发命令分发。
+        // `![image](img_v3_…)` 的首字符恰好是 `!` —— 2026-09-15 事故就是这么进 shell 的。
+        const stripped = stripPlaceholders(content);
+        if (stripped.unknownTags.length > 0) {
+            logger.warn(`[inbound] unknown placeholder tags stripped: ${stripped.unknownTags.join(', ')} ` +
+                `(msg_type=${msg.rawContentType})`);
         }
-        // `!` bash commands bypass the serial queue: they don't start claude and
-        // don't touch session state, so they must run in parallel with claude runs
-        // in the same workspace (design.md §9.6: the queue exists to prevent
-        // concurrent claude runs, not to serialize bash). router.handle dispatches
-        // `!` to bridge.executeBash, which tracks the run independently.
-        if (content.trim().startsWith('!')) {
+        const commandEligible = msg.rawContentType === 'text' && stripped.kinds.length === 0 && stripped.clean !== '';
+        // 命令消息旁路装配窗口：其它 /命令 立即执行，窗口内已装配的内容
+        // 作为独立提交冲刷（/stop 已在上面处理，立即生效不等待）。
+        if (commandEligible && (stripped.clean.startsWith('/') || stripped.clean.startsWith('!'))) {
+            void assembler.flush(msg.userId, msg.chatId, 'flush');
             void router
-                .handle(content, {
+                .handle(stripped.clean, {
                 userId: msg.userId,
                 chatId: msg.chatId,
                 messageId: msg.messageId,
-            })
-                .catch((err) => logger.error('[control] bang command failed:', err));
+            }, { allowCommandPrefix: true })
+                .catch((err) => logger.error('[control] command failed:', err));
             return;
         }
-        // Compute workspace with same fallback logic as executeBash:
-        // 1. sessionStore cwd → 2. first saved workspace
-        let workspace = sessionStore.getCwd(msg.userId) ?? '';
-        if (!workspace && workspaceStore) {
-            const workspaces = workspaceStore.list();
-            if (workspaces.length > 0) {
-                // NOTE: fallback uses insertion order, not sort preference — by design
-                // (cwd fallback stays insertion-order for now)
-                workspace = workspaces[0].path;
-            }
-        }
-        // Step4/D4: 入队时刻（T0）快照 agent+session，随任务闭包带到 T1 执行时刻，
-        // 避免排队期间 /new、/config 改写 live 状态导致语义漂移（方案 D4）。唯一
-        // 捕获点 Bridge.currentBinding。
-        const binding = bridge.currentBinding(msg.userId);
-        bridge.enqueue(workspace, async () => {
-            await router.handle(content, {
-                userId: msg.userId,
-                chatId: msg.chatId,
-                messageId: msg.messageId,
-            }, 
-            // P1-14: lane 与执行 cwd 同源 —— 入队时捕获的 workspace 显式传给
-            // forwardToClaude，排队期间 /cd 不再导致旧 lane 消息被 busy-drop。
-            // D4/Step4: binding 同源 —— 入队时快照的 agent+session 一并透传，
-            // 排队期间 /new、/config 不再导致旧 lane 消息语义漂移。
-            { cwdOverride: workspace, binding });
-        }, {
-            taskMeta: {
-                userId: msg.userId,
-                chatId: msg.chatId,
-                messageId: msg.messageId,
-                messagePreview: content.slice(0, 3000),
-                // D3/Step4: binding 随 taskMeta 存进 QueuedTask，供替换闭包
-                // （queue.edit/queue.immediate）复用，不重新快照。
-                binding,
-            },
+        // 普通消息：进装配器，等静默期窗口到期（下载落定）后合并成一个 turn。
+        assembler.ingest({
+            kind: 'text',
+            userId: msg.userId,
+            chatId: msg.chatId,
+            messageId: msg.messageId,
+            replyToMessageId: msg.replyToMessageId,
+            rawContentType: msg.rawContentType,
+            text: stripped.clean,
+            placeholders: stripped.kinds,
+            unknownTags: stripped.unknownTags,
         });
     });
     connector.setCardActionHandler(async (action) => {

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/config/opencode.d.ts

@@ -2,7 +2,7 @@
  * OpenCode config builder — builds fields and handles field changes for OpenCode agent.
  */
 import type { AgentConfigCardBuilder, ConfigField } from './types.js';
-import type { AppConfig } from '../../config/index.js';
+import { type AppConfig } from '../../config/index.js';
 export declare class OpencodeConfigBuilder implements AgentConfigCardBuilder {
     buildFields(displayConfig: AppConfig): ConfigField[];
     handleFieldChange(key: string, value: unknown, config: AppConfig): Array<{

package/dist/router/config/opencode.js

@@ -2,6 +2,7 @@
  * OpenCode config builder — builds fields and handles field changes for OpenCode agent.
  */
 import { loadOpencodeConfig } from '../../config/opencode-config.js';
+import { DEFAULT_TURN_IDLE_TIMEOUT_MINUTES } from '../../config/index.js';
 import { resetModelPatch } from './common/model-patch.js';
 const MODE_OPTIONS = [
     { text: 'build（默认，逐项审批）', value: 'build' },
@@ -38,6 +39,16 @@ export class OpencodeConfigBuilder {
             options: MODE_OPTIONS,
             currentValue: currentMode,
         });
+        // Turn 空闲超时（纯 ACP 对齐 kimi：卡片暴露 turnIdleTimeoutMinutes，
+        // binary/requestTimeoutMs/idleTtlMs 为 YAML-only 工程参数）
+        const currentTurnIdleTimeoutMinutes = displayConfig.agents?.opencode?.acp?.turnIdleTimeoutMinutes ??
+            DEFAULT_TURN_IDLE_TIMEOUT_MINUTES;
+        fields.push({
+            key: 'agents.opencode.acp.turnIdleTimeoutMinutes',
+            label: 'Turn 空闲超时(分钟, 0关闭)',
+            type: 'input',
+            currentValue: String(currentTurnIdleTimeoutMinutes),
+        });
         return fields;
     }
     handleFieldChange(key, value, config) {

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. */
@@ -121,6 +131,11 @@ export declare class CommandRouter {
      * returns its pid. Injected from index.ts; /restart is unavailable without it.
      */
     private restartSpawner?;
+    /**
+     * 冲刷装配器窗口内未提交的入站 turn（/exit、/restart 干净退出前调用，
+     * 避免静默期窗口内的内容丢失）。index.ts 注入。
+     */
+    private flushInbound?;
     private idleTimeoutMs;
     /** Dev mode flag: --dev means the bridge was started from source (bun src/index.ts). */
     private devMode;
@@ -197,12 +212,24 @@ export declare class CommandRouter {
      * The reader is fetched from the registry each time to reflect config changes.
      */
     private get sessionReader();
+    /**
+     * 注入入站装配器的冲刷回调（/exit、/restart 干净退出前调用，
+     * 避免静默期窗口内未提交的 turn 丢失）。index.ts 在构造后接线。
+     */
+    setInboundFlusher(flush: () => Promise<void>): void;
     /**
      * Route a message: if it starts with /, handle as command; if it starts with !, execute as bash; otherwise forward to Claude.
+     *
+     * 命令识别前置条件（2026-09-15 P0 修复）：
+     * 裸前缀判定会被结构占位符命中 —— SDK 把富文本里的图片渲染成 `![image](img_v3_…)`，
+     * 首字符恰好是 `!`，整段用户消息被当 shell 命令执行（`executeBash "[image](img_v3_…"`）。
+     * 因此命令前缀只在「调用方声明纯文本 + 剥离占位符后非空且无占位符 + 首字符是 / 或 !」
+     * 三条同时成立时生效，其余一律按文本转发。
      */
     handle(message: string, ctx: CommandContext, opts?: {
         cwdOverride?: string;
         binding?: AgentBinding;
+        allowCommandPrefix?: boolean;
     }): Promise<CommandResult | null>;
     /**
      * 一次别名展开：bridge 收到用户消息后、命令分发前调用。
@@ -270,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.
@@ -314,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;
     /**
@@ -339,7 +375,7 @@ export declare class CommandRouter {
      */
     private handleOrderPage;
     /**
-     * Handle order.aliasEdit: 展示别名编辑卡（input + ✓ 提交图标）。
+     * Handle order.aliasEdit: 展示别名编辑卡（input，回车/完成键提交）。
      * 有别名时预填；提交 `order.aliasInput` 处理（含校验与唯一性）。
      */
     /**
@@ -356,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 →
@@ -391,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'.
@@ -514,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`）：把本地文件直接发送到飞书。
      *
@@ -530,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).