lark-remote 0.4.1 → 0.4.3

package/dist/platform/shell.js

@@ -1,6 +1,16 @@
 import { currentPlatform, isWin32 } from './select.js';
 import { resolveExecutable } from './command.js';
 import { spawnProcess } from './spawn.js';
+/** 首 token 是这些名字时按「要一个 shell」处理（win32 上它们只能来自 Git Bash）。 */
+const SHELL_COMMANDS = new Set(['bash', 'sh', 'zsh', 'dash']);
+/** 取命令名（去目录、去扩展名、小写）：`C:\Program Files\Git\bin\bash.exe` → `bash`。 */
+function commandBaseName(file) {
+    const base = file.split(/[/\\]/).pop() ?? file;
+    const dot = base.lastIndexOf('.');
+    return (dot > 0 ? base.slice(0, dot) : base).toLowerCase();
+}
+const MISSING_GIT_BASH_MESSAGE = 'Windows 上执行 bash 命令需要 Git Bash（未在 PATH 中找到 bash.exe）；' +
+    '请安装 Git for Windows 后重试';
 /** shell 不可用（如 win32 上没装 Git Bash）：调用方应转成明确错误卡。 */
 export class ShellUnavailableError extends Error {
     kind;
@@ -18,12 +28,33 @@ export function createBashShellBackend(deps = {}) {
         spawn(command, opts) {
             return spawnFn('bash', ['-c', command], { cwd: opts.cwd, ...opts.options });
         },
+        spawnArgv(file, args, opts = {}) {
+            // posix 不做任何翻译：调用方给的 argv 已经是最终形态（迁移前行为）。
+            return spawnFn(file, [...args], { cwd: opts.cwd, ...opts.options });
+        },
     };
 }
 /** win32 后端：默认 Git Bash，powershell/cmd 为显式用户选择。 */
 export function createWin32ShellBackend(deps = {}) {
     const spawnFn = deps.spawn ?? spawnProcess;
     const kind = deps.kind ?? 'bash';
+    /**
+     * argv 路径与「`!` 用哪个 shell」无关：ACP 的 terminal/create 要的是 bash
+     * 本身，因此三种后端的 spawnArgv 共用同一套语义（shell 名 → Git Bash，
+     * 其余按 PATH/PATHEXT 透传）。
+     */
+    const spawnArgv = (file, args, opts = {}) => {
+        const spawnOpts = { cwd: opts.cwd, ...opts.options, windowsHide: true };
+        if (!SHELL_COMMANDS.has(commandBaseName(file))) {
+            return spawnFn(file, [...args], spawnOpts);
+        }
+        const resolve = deps.resolve ?? resolveExecutable;
+        const spec = resolve('bash', { platform: 'win32', pathEnv: deps.pathEnv });
+        if (!spec) {
+            throw new ShellUnavailableError('bash', MISSING_GIT_BASH_MESSAGE);
+        }
+        return spawnFn(spec.file, [...args], spawnOpts);
+    };
     if (kind === 'powershell') {
         return {
             kind,
@@ -34,6 +65,7 @@ export function createWin32ShellBackend(deps = {}) {
                     windowsHide: true,
                 });
             },
+            spawnArgv,
         };
     }
     if (kind === 'cmd') {
@@ -46,6 +78,7 @@ export function createWin32ShellBackend(deps = {}) {
                     windowsHide: true,
                 });
             },
+            spawnArgv,
         };
     }
     return {
@@ -54,8 +87,7 @@ export function createWin32ShellBackend(deps = {}) {
             const resolve = deps.resolve ?? resolveExecutable;
             const spec = resolve('bash', { platform: 'win32', pathEnv: deps.pathEnv });
             if (!spec) {
-                throw new ShellUnavailableError('bash', 'Windows 上执行 bash 命令需要 Git Bash（未在 PATH 中找到 bash.exe）；' +
-                    '请安装 Git for Windows 后重试');
+                throw new ShellUnavailableError('bash', MISSING_GIT_BASH_MESSAGE);
             }
             // 执行语义由 cross-spawn 负责（垫片 cmd.exe 受控执行）；这里只保证
             // bash 存在性并给出明确的「需要 Git Bash」错误
@@ -65,6 +97,7 @@ export function createWin32ShellBackend(deps = {}) {
                 windowsHide: true,
             });
         },
+        spawnArgv,
     };
 }
 /** 平台分发的唯一入口：posix → bash，win32 → 默认 Git Bash。 */

package/dist/platform/sleep-blocker.d.ts

@@ -12,6 +12,12 @@ export interface SleepBlockerOptions {
 /**
  * PowerShell 托管脚本：声明 P/Invoke → 设置持续唤醒 → 轮询父 pid 直至父进程消失。
  * 单字符串经 `-Command` 传入（不经 shell，内嵌双引号安全）；父 pid 是 number，插值安全。
+ *
+ * 首句 `$ErrorActionPreference = 'Stop'` 把非终止错误**升级为终止错误**：P/Invoke
+ * 声明或调用一旦出问题，helper 立刻退出，从而走到 startSleepBlocker 的 `exit`
+ * 告警路径。否则「进程活着但 execution state 没设置上」属于静默态，日志里查不出来。
+ * 看门循环自带 `-ErrorAction SilentlyContinue`，不受该设置影响（父进程消失本就是
+ * 正常结束路径）。
  */
 export declare function win32SleepBlockerScript(parentPid: number): string;
 export declare function startSleepBlocker(opts: SleepBlockerOptions): SleepBlocker | null;

package/dist/platform/sleep-blocker.js

@@ -1,15 +1,39 @@
 import { spawnProcess } from './spawn.js';
 import { getLogger } from '../logger/index.js';
-/** ES_CONTINUOUS (0x80000000) | ES_SYSTEM_REQUIRED (0x00000001)。 */
-const ES_FLAGS = '0x80000001';
+/**
+ * ES_CONTINUOUS (0x80000000) | ES_SYSTEM_REQUIRED (0x00000001)。
+ *
+ * **必须按无符号 32 位取值**：`0x80000001` = 2147483649 超出 Int32 正数上界
+ * （2147483647），而 PowerShell 的数字字面量按 Int32 解析 —— 十六进制写法一旦
+ * 进了脚本就会被解析成 **-2147483647**，传给 P/Invoke 声明的 `uint` 形参时抛
+ * `MethodArgumentConversionInvalidCastArgument`（2026-09-22 真机复现）。
+ */
+const ES_FLAGS_UINT32 = (0x80000000 | 0x00000001) >>> 0;
+/**
+ * 插入 PowerShell 脚本的 ES flags 字面量，**十进制**（`2147483649`）。
+ *
+ * 上面那个异常是**非终止错误**：PowerShell 不中断脚本，后面的看门循环照跑 ——
+ * 于是 helper 进程一直活着、`SetThreadExecutionState` 却从未被调用，防休眠彻底
+ * 失效，而「helper 退出」这条唯一的告警通道恰好不触发（日志里只剩一句 `active`，
+ * 系统照记 Kernel-Power id=42 / System Idle 睡眠）。十进制字面量走
+ * Int64 → UInt32 转换，可安全传递。
+ */
+const WIN32_ES_FLAGS_LITERAL = String(ES_FLAGS_UINT32);
 /**
  * PowerShell 托管脚本：声明 P/Invoke → 设置持续唤醒 → 轮询父 pid 直至父进程消失。
  * 单字符串经 `-Command` 传入（不经 shell，内嵌双引号安全）；父 pid 是 number，插值安全。
+ *
+ * 首句 `$ErrorActionPreference = 'Stop'` 把非终止错误**升级为终止错误**：P/Invoke
+ * 声明或调用一旦出问题，helper 立刻退出，从而走到 startSleepBlocker 的 `exit`
+ * 告警路径。否则「进程活着但 execution state 没设置上」属于静默态，日志里查不出来。
+ * 看门循环自带 `-ErrorAction SilentlyContinue`，不受该设置影响（父进程消失本就是
+ * 正常结束路径）。
  */
 export function win32SleepBlockerScript(parentPid) {
     return [
+        `$ErrorActionPreference = 'Stop'`,
         `Add-Type -TypeDefinition 'using System.Runtime.InteropServices; public static class SleepBlocker { [DllImport("kernel32.dll")] public static extern uint SetThreadExecutionState(uint esFlags); }'`,
-        `[SleepBlocker]::SetThreadExecutionState(${ES_FLAGS}) | Out-Null`,
+        `[SleepBlocker]::SetThreadExecutionState(${WIN32_ES_FLAGS_LITERAL}) | Out-Null`,
         `while (Get-Process -Id ${parentPid} -ErrorAction SilentlyContinue) { Start-Sleep -Seconds 30 }`,
     ].join('; ');
 }
@@ -47,8 +71,10 @@ export function startSleepBlocker(opts) {
         logger.warn(`[sleep-blocker] ${command} error:`, err);
     });
     // helper 意外死亡 = 防休眠静默失效（win32 上 Add-Type 动态编译被企业策略/
-    // 杀软拦掉、Get-Process 权限失败；darwin 上 caffeinate 早退）。桥此时还活着，
-    // 是唯一能留痕的时机——否则日志里只剩启动那句 "active"，误以为防休眠在生效。
+    // 杀软拦掉、P/Invoke 调用抛错——脚本首句已用 $ErrorActionPreference='Stop' 把
+    // 非终止错误升级为终止错误，确保这类失败能落到这条分支；darwin 上 caffeinate
+    // 早退）。桥此时还活着，是唯一能留痕的时机——否则日志里只剩启动那句 "active"，
+    // 误以为防休眠在生效。
     let stopping = false;
     proc.on('exit', (code, signal) => {
         if (stopping)

package/dist/platform/spawn.d.ts

@@ -22,7 +22,7 @@ export declare function mergeProcessEnv(base?: NodeJS.ProcessEnv, overrides?: No
 /**
  * 是否需要为子进程建独立进程组（`spawn` 的 `detached: true`）。
  *
- * posix：ProcessStopper 的组杀用负 PID（`kill(-pgid)`），子进程必须是组长，
+ * posix：Terminator 的组杀用负 PID（`kill(-pgid)`），子进程必须是组长，
  * 否则 kill 抛 ESRCH 被吞，停止/清理链路全失效。
  *
  * win32：组杀已由 terminator 的 `taskkill /PID <pid> /T /F` 树杀替代，不需要

package/dist/platform/spawn.js

@@ -53,7 +53,7 @@ const COMMAND_NOT_FOUND_PATTERN = /is not recognized as an internal or external
 /**
  * 是否需要为子进程建独立进程组（`spawn` 的 `detached: true`）。
  *
- * posix：ProcessStopper 的组杀用负 PID（`kill(-pgid)`），子进程必须是组长，
+ * posix：Terminator 的组杀用负 PID（`kill(-pgid)`），子进程必须是组长，
  * 否则 kill 抛 ESRCH 被吞，停止/清理链路全失效。
  *
  * win32：组杀已由 terminator 的 `taskkill /PID <pid> /T /F` 树杀替代，不需要

package/dist/platform/terminator-posix.d.ts

@@ -1,17 +1,5 @@
-/**
- * posix 终止器：`src/runner/common/process-stopper.ts` 的原样迁移（design.md §3.2）。
- *
- * 语义与迁移前逐条对齐：SIGTERM 打负 PID 进程组 → 等 graceMs → SIGKILL；
- * immediate 则两个信号连发。本次只新增两样东西：
- *   - 返回 {@link TerminateResult} 让终止途经可观测（与 win32 同构）；
- *   - `cleanupOnExit`（Terminator 接口要求的进程级退出清理）。
- *
- * `ProcessStopper` 保留为兼容壳：行为（含日志文案）零变化，既有调用方与
- * 测试无需改动；M2 调用点迁移时逐个换成 Terminator 后即可删除。
- */
-import type { ChildProcess } from 'node:child_process';
 import type { Terminator } from './terminator.js';
-export type LogLevel = 'debug' | 'info';
+export type LogLevel = 'debug' | 'info' | 'warn';
 export type TerminatorLogger = (level: LogLevel, message: string) => void;
 export interface PosixTerminatorDeps {
     /** 优雅等待窗口（毫秒），对应现状 stopGraceMs */
@@ -20,19 +8,3 @@ export interface PosixTerminatorDeps {
     log?: TerminatorLogger;
 }
 export declare function createPosixTerminator(deps: PosixTerminatorDeps): Terminator;
-interface ProcessStopperOptions {
-    graceMs: number;
-}
-interface StopOptions {
-    immediate?: boolean;
-}
-/**
- * 迁移前的类名（兼容壳）：返回 void、接受 null proc。
- * 新代码请用 {@link createPosixTerminator} / `createTerminator`。
- */
-export declare class ProcessStopper {
-    private graceMs;
-    constructor(opts: ProcessStopperOptions);
-    stop(proc: ChildProcess | null, opts?: StopOptions): Promise<void>;
-}
-export {};

package/dist/platform/terminator-posix.js

@@ -4,6 +4,8 @@ function defaultLog(level, message) {
     const logger = getLogger();
     if (level === 'debug')
         logger.debug(message);
+    else if (level === 'warn')
+        logger.warn(message);
     else
         logger.info(message);
 }
@@ -11,6 +13,24 @@ function defaultLog(level, message) {
 function isAlive(proc) {
     return proc.exitCode === null && proc.signalCode === null;
 }
+/**
+ * 向进程组发一个信号；返回失败原因，null 表示已送达或无需送达。
+ *
+ * ESRCH（进程组已经没了）与杀成功同等处置——这正是「停止」想要的结果；
+ * 其余失败（EPERM 等）必须报出去，否则调用方拿到假成功，事后既不知也没得查。
+ */
+function signalGroup(pgid, signal) {
+    try {
+        process.kill(pgid, signal);
+        return null;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ESRCH')
+            return null;
+        return `${signal} 未送达 pgid=${pgid}: ${code ?? err.message}`;
+    }
+}
 async function stopPosix(proc, opts, log) {
     if (!isAlive(proc)) {
         return { requested: false, via: 'already-exited' };
@@ -22,19 +42,17 @@ async function stopPosix(proc, opts, log) {
     // 负 PID = 整个进程组：shell 包装层与孙进程一并带走
     const pgid = -pid;
     log('debug', `[process-stopper] sending SIGTERM to pgid=${pgid} immediate=${opts.immediate}`);
-    try {
-        process.kill(pgid, 'SIGTERM');
-    }
-    catch {
-        /* process may have exited */
+    const termErr = signalGroup(pgid, 'SIGTERM');
+    if (termErr) {
+        log('warn', `[process-stopper] ${termErr}`);
+        return { requested: false, via: 'cooperative', error: termErr };
     }
     if (opts.immediate) {
         // 不等待：SIGKILL 紧随其后；进程已死时 kill 抛 ESRCH，忽略即可
-        try {
-            process.kill(pgid, 'SIGKILL');
-        }
-        catch {
-            /* process already gone */
+        const killErr = signalGroup(pgid, 'SIGKILL');
+        if (killErr) {
+            log('warn', `[process-stopper] ${killErr}`);
+            return { requested: false, via: 'taskkill', error: killErr };
         }
         return { requested: true, via: 'taskkill' };
     }
@@ -54,11 +72,10 @@ async function stopPosix(proc, opts, log) {
         clearTimeout(graceTimer);
     if (!exited) {
         log('info', `[process-stopper] process group ${pgid} did not exit within grace period, sending SIGKILL`);
-        try {
-            process.kill(pgid, 'SIGKILL');
-        }
-        catch {
-            /* process already gone */
+        const killErr = signalGroup(pgid, 'SIGKILL');
+        if (killErr) {
+            log('warn', `[process-stopper] ${killErr}`);
+            return { requested: false, via: 'taskkill', error: killErr };
         }
         return { requested: true, via: 'taskkill' };
     }
@@ -85,19 +102,4 @@ export function createPosixTerminator(deps) {
         },
     };
 }
-/**
- * 迁移前的类名（兼容壳）：返回 void、接受 null proc。
- * 新代码请用 {@link createPosixTerminator} / `createTerminator`。
- */
-export class ProcessStopper {
-    graceMs;
-    constructor(opts) {
-        this.graceMs = opts.graceMs;
-    }
-    async stop(proc, opts) {
-        if (!proc)
-            return;
-        await stopPosix(proc, { graceMs: this.graceMs, immediate: opts?.immediate === true }, defaultLog);
-    }
-}
 //# sourceMappingURL=terminator-posix.js.map

package/dist/platform/terminator-win32.js

@@ -74,10 +74,12 @@ export function createWin32Terminator(deps) {
                 return { requested: true, via: 'taskkill' };
             }
             const agent = deps.agent;
-            const stopper = agent === undefined ? undefined : stoppers.get(agent);
+            // 按 agent + pid 查：同一 agent 可能有多条长驻连接（每 workspace 一条），
+            // 只有 pid 能把通道归属钉到手上这个 proc 上。
+            const stopper = agent === undefined ? undefined : stoppers.get(agent, proc.pid);
             if (!stopper) {
                 // 无通道是合法状态：显式记录后走树杀，不做无意义的优雅空转
-                log?.(`win32 优雅停止跳过：agent=${agent ?? '(unknown)'} 无协议停止通道，直接树杀`);
+                log?.(`win32 优雅停止跳过：agent=${agent ?? '(unknown)'} pid=${proc.pid} 无协议停止通道，直接树杀`);
                 killTree(proc.pid);
                 return { requested: true, via: 'skipped-no-channel' };
             }

package/dist/platform/terminator.d.ts

@@ -13,7 +13,7 @@ export type { AgentStopper } from './agent-stopper.js';
 /**
  * 进程终止器。
  *
- * `stop` 的 `immediate` 语义与现状 `process-stopper` 的 `stop({immediate})` 对齐。
+ * `stop` 的 `immediate` 语义与原 `process-stopper` 的 `stop({immediate})` 对齐。
  * 设计文档声明返回 `Promise<void>`，这里收窄为 {@link TerminateResult}：降级
  * 必须可观测（优雅段被跳过、走了树杀、进程早已退出），否则 win32 上「等一个
  * 不会来的退出事件」这类退化无法被发现。
@@ -35,7 +35,7 @@ export interface TerminatorDeps {
     /** 协议通道注册表注入（测试隔离）；默认进程级单例 */
     stoppers?: AgentStopperRegistry;
     /** 日志注入（测试用）；默认走 logger 单例 */
-    log?: (level: 'debug' | 'info', message: string) => void;
+    log?: (level: 'debug' | 'info' | 'warn', message: string) => void;
 }
 /**
  * 唯一的终止器选择入口：posix 走组杀，win32 走「协议通道 + taskkill 树杀」。

package/dist/platform/terminator.js

@@ -1,24 +1,39 @@
+import { getLogger } from '../logger/index.js';
 import { currentPlatform, isWin32 } from './select.js';
 import { createPosixTerminator } from './terminator-posix.js';
 import { createWin32Terminator } from './terminator-win32.js';
 // 注册表实现在 agent-stopper.ts（避免与 terminator-win32.ts 循环依赖），
 // 这里 re-export 以维持调用方的单一入口。
 export { AgentStopperRegistry, agentStopperRegistry } from './agent-stopper.js';
+/** 默认日志出口：seam 底层（terminator-win32/posix）不反向依赖 logger 单例，由这里接线。 */
+function defaultTerminatorLog(level, message) {
+    const logger = getLogger();
+    if (level === 'debug')
+        logger.debug(message);
+    else if (level === 'warn')
+        logger.warn(message);
+    else
+        logger.info(message);
+}
 /**
  * 唯一的终止器选择入口：posix 走组杀，win32 走「协议通道 + taskkill 树杀」。
  * 其余模块一律拿这里的 Terminator，禁止散落平台 if（§2.2）。
  */
 export function createTerminator(deps) {
     const platform = deps.platform ?? currentPlatform;
+    // 默认日志出口必须真的接上：win32 的「无协议通道 → 直接树杀」「协议通道抛错
+    // → 转树杀」以及 posix 的 grace 超时都是设计要求的可观测降级信号（§3.2），
+    // 缺省 undefined 会让这些信号全部静默消失。
+    const log = deps.log ?? defaultTerminatorLog;
     if (isWin32(platform)) {
         return createWin32Terminator({
             graceMs: deps.graceMs,
             agent: deps.agent,
             stoppers: deps.stoppers,
             // win32 侧日志不带级别（无 debug 级输出），统一按 info 透传
-            log: deps.log ? (message) => deps.log?.('info', message) : undefined,
+            log: (message) => log('info', message),
         });
     }
-    return createPosixTerminator({ graceMs: deps.graceMs, log: deps.log });
+    return createPosixTerminator({ graceMs: deps.graceMs, log });
 }
 //# sourceMappingURL=terminator.js.map

package/dist/platform/types.d.ts

@@ -18,6 +18,9 @@ export interface TerminateResult {
     /**
      * 终止途经：协议停止 / 强制终止 / 进程已退出 / 无通道跳过优雅段。
      * 强制终止在 posix 下是 SIGKILL 组杀、win32 下是 taskkill 树杀，同枚举值。
+     * `requested: false` 时取值为**尝试过的那条途经**，配合 {@link error} 判读。
      */
     via: 'cooperative' | 'taskkill' | 'already-exited' | 'skipped-no-channel';
+    /** 请求未送达的原因（ESRCH/进程已消失不算失败，不带此字段） */
+    error?: string;
 }

package/dist/router/card-action-feedback.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 非直返 card action 的异步回执判定（入口层的出站侧）。
+ *
+ * `src/index.ts` 的 card action 分发只有两类出口：`DIRECT_RETURN_CMDS` 同步
+ * return 给飞书回调（toast 能弹），其余走 `bridge.enqueueImmediate` /
+ * `bridge.enqueue`——fire-and-forget，回调响应早已被飞书收走，handler 返回的
+ * toast 无处可去。本模块给出异步出口应转发的文案：失败/告警换成一条持久文本
+ * 消息（卡片只承载成功态，失败在刷新后的卡片上完全看不出来），成功类不回执
+ * （逐次回执会把聊天刷成日志）。
+ */
+/**
+ * 从 `router.handleCardAction` 的返回值里取出应异步回给用户的文本。
+ *
+ * 返回 undefined = 无需回执。结构不合期望时同样返回 undefined（判定函数不得
+ * 成为 fire-and-forget 任务里新的抛错源）。
+ */
+export declare function actionFeedbackText(res: unknown): string | undefined;

package/dist/router/card-action-feedback.js

@@ -0,0 +1,31 @@
+/**
+ * 非直返 card action 的异步回执判定（入口层的出站侧）。
+ *
+ * `src/index.ts` 的 card action 分发只有两类出口：`DIRECT_RETURN_CMDS` 同步
+ * return 给飞书回调（toast 能弹），其余走 `bridge.enqueueImmediate` /
+ * `bridge.enqueue`——fire-and-forget，回调响应早已被飞书收走，handler 返回的
+ * toast 无处可去。本模块给出异步出口应转发的文案：失败/告警换成一条持久文本
+ * 消息（卡片只承载成功态，失败在刷新后的卡片上完全看不出来），成功类不回执
+ * （逐次回执会把聊天刷成日志）。
+ */
+/** 只转发这两类；success/info/loading 由原地刷新的卡片表达。 */
+const FORWARDABLE = new Set(['error', 'warning']);
+/**
+ * 从 `router.handleCardAction` 的返回值里取出应异步回给用户的文本。
+ *
+ * 返回 undefined = 无需回执。结构不合期望时同样返回 undefined（判定函数不得
+ * 成为 fire-and-forget 任务里新的抛错源）。
+ */
+export function actionFeedbackText(res) {
+    const toast = res
+        ?.toast;
+    if (typeof toast !== 'object' || toast === null)
+        return undefined;
+    const { type, content } = toast;
+    if (typeof type !== 'string' || !FORWARDABLE.has(type))
+        return undefined;
+    if (typeof content !== 'string')
+        return undefined;
+    return content.trim() || undefined;
+}
+//# sourceMappingURL=card-action-feedback.js.map

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/claude.js

@@ -15,8 +15,10 @@ const PERMISSION_MODE_LABELS = {
     plan: '计划模式（只读探索）',
 };
 /**
- * 下拉选项排除 manual：manual 是 default 的别名（claude CLI 等价），
- * 只保留 default 一个，避免下拉出现两个等价项。schema 仍接受 manual（旧配置向后兼容）。
+ * 下拉不展示 manual：CLI 认这个值（claude --help），但它和 'default' 是两个不同的
+ * 配置口径（显式传参 vs 省略参数），并列展示用户无从分辨取舍，所以只留 'default'。
+ * 代价：配置里手写的 manual 在卡片上按 'default' 显示，改动其它项保存时会被写回
+ * 'default'（见 buildFields 的 displayedPermissionMode）。
  */
 const PERMISSION_MODE_OPTIONS = CLAUDE_PERMISSION_MODES.filter((m) => m !== 'manual').map((m) => ({
     text: `${m}（${PERMISSION_MODE_LABELS[m] ?? ''}）`,
@@ -78,10 +80,11 @@ export class ClaudeConfigBuilder {
             options: CLAUDE_EFFORTS,
             currentValue: currentEffort,
         });
-        // 权限模式（Claude 官方 --permission-mode 枚举；bypassPermissions 为 schema 默认，
-        // 保持旧行为无审批卡，配置为其他值后激活交互式审批）
+        // 权限模式（取值见 CLAUDE_PERMISSION_MODES：除自造的 default 外都是 CLI 的
+        // --permission-mode 枚举；bypassPermissions 为 schema 默认，保持旧行为无审批卡，
+        // 配置为其他值后激活交互式审批）
         const currentPermissionMode = displayConfig.claude?.permissionMode ?? 'bypassPermissions';
-        // manual 是 default 的别名：旧配置按 default 显示（下拉无 manual 项，避免空选）
+        // manual 不在下拉里：旧配置按 default 显示，避免打开卡片时该项空选
         const displayedPermissionMode = currentPermissionMode === 'manual' ? 'default' : currentPermissionMode;
         fields.push({
             key: 'claude.permissionMode',