lark-remote 0.4.0 → 0.4.2

package/dist/router/index.js

@@ -9,8 +9,9 @@ import { OrderStore } from '../order/index.js';
 import { resolveAlias } from '../order/alias-resolve.js';
 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';
@@ -289,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',
@@ -321,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 {
@@ -342,6 +358,11 @@ export class CommandRouter {
      * returns its pid. Injected from index.ts; /restart is unavailable without it.
      */
     restartSpawner;
+    /**
+     * 冲刷装配器窗口内未提交的入站 turn（/exit、/restart 干净退出前调用，
+     * 避免静默期窗口内的内容丢失）。index.ts 注入。
+     */
+    flushInbound;
     idleTimeoutMs;
     /** Dev mode flag: --dev means the bridge was started from source (bun src/index.ts). */
     devMode;
@@ -416,13 +437,33 @@ export class CommandRouter {
     get sessionReader() {
         return this.sessionReaderRegistry.get(this.config.defaultAgent);
     }
+    /**
+     * 注入入站装配器的冲刷回调（/exit、/restart 干净退出前调用，
+     * 避免静默期窗口内未提交的 turn 丢失）。index.ts 在构造后接线。
+     */
+    setInboundFlusher(flush) {
+        this.flushInbound = flush;
+    }
     /**
      * 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_…"`）。
+     * 因此命令前缀只在「调用方声明纯文本 + 剥离占位符后非空且无占位符 + 首字符是 / 或 !」
+     * 三条同时成立时生效，其余一律按文本转发。
      */
     async handle(message, ctx, opts) {
         const trimmed = message.trim();
-        const startsWithBang = trimmed.startsWith('!');
-        const startsWithSlash = trimmed.startsWith('/');
+        // 双保险：任何调用点都必须先剥离结构占位符，再判命令前缀
+        //（index.ts 传 allowCommandPrefix = rawContentType === 'text'，但那层不是唯一入口）。
+        const guard = stripPlaceholders(trimmed);
+        // 默认 true：order.exec 等既有内部调用点传的是用户已确认的指令文本，
+        // 且剥离后无占位符 —— 默认放行不改变它们的语义（见 command-guard.test.ts）。
+        const allowCommandPrefix = opts?.allowCommandPrefix ?? true;
+        const commandEligible = allowCommandPrefix && guard.kinds.length === 0 && guard.clean !== '';
+        const startsWithBang = commandEligible && guard.clean.startsWith('!');
+        const startsWithSlash = commandEligible && guard.clean.startsWith('/');
         getLogger().info(`[router] handle message="${message.slice(0, 50)}..." trimmed="${trimmed.slice(0, 50)}..." startsWithSlash=${startsWithSlash} startsWithBang=${startsWithBang}`);
         // 复制分身流程活跃期：一切消息（含命令）交给 clone 状态机处理，
         // 不转发 coding agent、不进命令分发（index.ts 已在入队前拦截，这里
@@ -432,20 +473,20 @@ export class CommandRouter {
             return null;
         }
         if (startsWithSlash) {
-            const result = await this.executeCommand(trimmed, ctx);
+            const result = await this.executeCommand(guard.clean, ctx);
             if (result) {
                 await this.bridge.sendResult(result, ctx);
             }
             if (this.pendingExit) {
-                // 干净退出前冲刷待合批的媒体保存提示，避免 500ms 窗口内的提示丢失。
-                await this.bridge.flushAllMediaNotifications();
+                // 干净退出前冲刷装配器窗口内未提交的入站 turn，避免静默期窗口内的内容丢失。
+                await this.flushInbound?.();
                 this.exitHandler();
             }
             return result;
         }
         // Handle bang commands (!command)
-        if (trimmed.startsWith('!')) {
-            const cmd = trimmed.slice(1).trim();
+        if (startsWithBang) {
+            const cmd = guard.clean.slice(1).trim();
             if (!cmd) {
                 await this.bridge.sendResult({ text: '请输入要执行的命令，例如 !ls' }, ctx);
                 return null;
@@ -456,7 +497,9 @@ export class CommandRouter {
         // Forward to Claude (P1-14: pass the enqueue-time workspace through so the
         // run uses the same cwd as the serial queue lane, even if /cd ran while
         // the message was queued)
-        await this.bridge.forwardToClaude(trimmed, ctx, opts);
+        // 剥离占位符后再转发：agent 只该看到用户文本（附图已转成 attachments 块，
+        // 那是装配器生成的协议块，stripPlaceholders 会原样保留）。
+        await this.bridge.forwardToClaude(guard.clean, ctx, opts);
         return null;
     }
     /**
@@ -496,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':
@@ -607,7 +654,7 @@ export class CommandRouter {
                     // 必须同样消费，否则点击 /restart 按钮 spawn 成功后旧进程不退出，
                     // 新进程撞单例锁退出 → 重启两头落空（2026-08-01 红绿 anchor 锁定）。
                     if (this.pendingExit) {
-                        await this.bridge.flushAllMediaNotifications();
+                        await this.flushInbound?.();
                         this.exitHandler();
                     }
                     return;
@@ -904,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）。
@@ -924,7 +971,7 @@ export class CommandRouter {
                     { tag: 'hr' },
                     {
                         tag: 'div',
-                        text: { tag: 'lark_md', content: '💡 输入新内容后点击右侧 ✓ 提交图标' },
+                        text: { tag: 'lark_md', content: '💡 输入新内容后按回车提交' },
                     },
                     {
                         tag: 'column_set',
@@ -1098,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);
     }
@@ -1132,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.
@@ -1259,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);
@@ -1333,7 +1409,7 @@ export class CommandRouter {
         return { toast: { type: 'success', content: '' } };
     }
     /**
-     * Handle order.aliasEdit: 展示别名编辑卡（input + ✓ 提交图标）。
+     * Handle order.aliasEdit: 展示别名编辑卡（input，回车/完成键提交）。
      * 有别名时预填；提交 `order.aliasInput` 处理（含校验与唯一性）。
      */
     /**
@@ -1353,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',
@@ -1408,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 ?? '',
@@ -1452,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 →
@@ -1464,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 ?? '',
@@ -1566,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'.
@@ -1578,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}` },
@@ -1713,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;
@@ -2581,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
@@ -2637,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;
@@ -2684,6 +2780,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                             path: targetDir,
                             offset: safeOffset,
                             root: browseRoot,
+                            ...(filter ? { q: filter } : {}),
                         },
                     },
                 ],
@@ -2735,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({
@@ -2744,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) {
@@ -2800,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' });
@@ -2917,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': {
@@ -2966,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';
@@ -2982,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
@@ -2992,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.
@@ -3031,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 } : {}) },
+                                            },
+                                        ],
                                     },
                                 ],
                             },
@@ -3059,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 } : {}),
+                                                    },
                                                 },
                                             ],
                                         },
@@ -3077,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 } : {}),
+                                                    },
                                                 },
                                             ],
                                         },
@@ -3096,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: '➡',
@@ -3808,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',