lark-remote 0.4.1 → 0.4.3

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 ?? '',
@@ -1576,13 +1624,15 @@ export class CommandRouter {
         if (!name) {
             return { toast: { type: 'error', content: CARD_PAYLOAD_MISSING } };
         }
-        // Execute the removal (consumes the write-side effect; the returned text
-        // is discarded — feedback flows through the toast + refreshed card).
-        this.cmdWs(['remove', name], ctx);
+        // Execute the removal and let its result decide the toast: the card can be
+        // a stale list (alias already deleted elsewhere), and an unconditional
+        // "已删除" would then contradict what the refreshed card shows.
+        const result = this.cmdWs(['remove', name], ctx);
+        const text = result.text ?? `删除 workspace "${name}" 失败`;
         // Rebuild the /ws list card and update it in place, preserving the page
         // the user was on when they clicked 删除.
         await this.refreshListCard('ws', value, ctx);
-        return { toast: { type: 'success', content: `已删除 workspace "${name}"` } };
+        return { toast: { type: text.startsWith('已删除') ? 'success' : 'error', content: text } };
     }
     /**
      * Handle ws.page: paginate the /ws list in place.
@@ -1594,9 +1644,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 +1665,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 +1800,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 +2668,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
@@ -2651,22 +2713,48 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         const browseRoot = rootDir ? path.resolve(cwd, rootDir) : targetDir;
         try {
             const entries = fs.readdirSync(targetDir, { withFileTypes: true });
-            // Separate directories and files
-            const dirs = entries
-                .filter((e) => e.isDirectory())
-                .sort((a, b) => a.name.localeCompare(b.name));
-            const files = entries.filter((e) => e.isFile()).sort((a, b) => a.name.localeCompare(b.name));
+            // 逐条目分类。`Dirent.isFile()/isDirectory()` 对符号链接恒 false（旧实现
+            // 因此完全不列链接）；必须 stat 解析目标。单条目 stat 失败（悬空链接、
+            // readdir 与 stat 之间被删、无权限）只让该条目降级为「大小未知」，不能
+            // 让整次列目录失败——一个坏邻居毁掉整张卡是旧实现的第二宗罪。
+            const dirs = [];
+            const files = [];
+            for (const entry of entries) {
+                let isDir = entry.isDirectory();
+                let size;
+                if (!isDir) {
+                    try {
+                        const st = fs.statSync(path.join(targetDir, entry.name));
+                        isDir = st.isDirectory();
+                        if (!isDir)
+                            size = st.size;
+                    }
+                    catch {
+                        // 目标拿不到：按文件列出，size 留空
+                    }
+                }
+                if (isDir)
+                    dirs.push(entry.name);
+                else
+                    files.push({ name: entry.name, size });
+            }
+            dirs.sort((a, b) => a.localeCompare(b));
+            files.sort((a, b) => a.name.localeCompare(b.name));
             // Merge dirs and files for pagination, preserving type info
             const allItems = [
-                ...dirs.map((d) => ({ name: d.name, isDir: true })),
-                ...files.map((f) => ({
-                    name: f.name,
-                    isDir: false,
-                    size: fs.statSync(path.join(targetDir, f.name)).size,
-                })),
+                ...dirs.map((name) => ({ name, isDir: true })),
+                ...files.map((f) => ({ name: f.name, isDir: false, size: f.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 +2800,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                             path: targetDir,
                             offset: safeOffset,
                             root: browseRoot,
+                            ...(filter ? { q: filter } : {}),
                         },
                     },
                 ],
@@ -2763,8 +2852,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 +2862,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 +2945,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 +3062,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 +3118,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 +3135,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 +3152,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 +3213,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 +3246,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 +3269,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 +3293,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 +4006,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/claude/runner.js

@@ -7,7 +7,7 @@
  *
  * 架构：ClaudeRunner 是 workspace-lifetime 的薄包装，进程与协议细节在
  * ClaudeSession（src/runner/claude/session.ts，extends SpawningRunner 复用
- * pid 文件/killOrphan/ProcessStopper/心跳/退出分发器机制）。每次 run() 委托
+ * pid 文件/killOrphan/Terminator/心跳/退出分发器机制）。每次 run() 委托
  * session：确保进程（可 --resume）→ 写 user 消息 → 消费事件直到本 turn result。
  */
 import { ClaudeSessionReader } from '../../session/claude/index.js';

package/dist/runner/claude/session.d.ts

@@ -25,7 +25,7 @@
  * 生命周期：一个 workspace 一个长驻进程（lifetime='workspace'）。每次
  * run(message) = 写一条 user 消息 + 消费 stdout 事件直到本 turn 的 result；
  * 进程在 turn 之间保持存活（stdin 不关闭），/stop / /new / /cd / 看门狗超时
- * 时经 ProcessStopper 组杀，下条消息按 SessionStore 的 sessionId --resume。
+ * 时经 Terminator 组杀，下条消息按 SessionStore 的 sessionId --resume。
  */
 import { SpawningRunner } from '../common/spawning-runner.js';
 import type { AgentEvent, SpawnOptions } from '../types.js';
@@ -54,7 +54,7 @@ export interface PermissionResult {
 }
 /**
  * ClaudeSession extends SpawningRunner 复用其 spawn/pid 文件/killOrphan/
- * ProcessStopper/SpawnHeartbeat/退出分发器机制（P1-1/P1-10/P1-11 契约保持），
+ * Terminator/SpawnHeartbeat/退出分发器机制（P1-1/P1-10/P1-11 契约保持），
  * 但 run() 覆盖为「长驻 + 按 turn 消费」：进程跨 turn 存活，turn 结束以
  * stream-json result 事件（非 compact）为界，而不是进程退出。
  */
@@ -107,10 +107,6 @@ export declare class ClaudeSession extends SpawningRunner {
      * 直到本 turn 的 result。进程在 turn 结束后保持存活，供下一条消息复用。
      */
     run(message: string, opts: SpawnOptions): AsyncGenerator<AgentEvent>;
-    /**
-     * 写一条用户消息到 stdin（--input-format stream-json 的 user 事件）。
-     */
-    sendUserMessage(message: string): Promise<void>;
     /**
      * 回写审批响应（允许/拒绝）。
      */